# Extension Points for Widgets

YouTrack offers a collection of extension points where an app developer can embed a widget in the UI. These widgets support specific interactions that are not available to users unless they install and activate the app. On this page, you can find information about these extension points.

Here is the overview of all possible extension points with their scopes. To learn about widget scopes, see [Scope](apps-reference-http-handlers.html#scope).

| Extension Point | Scope | Description |
| --- | --- | --- |
| [ADMINISTRATION_MENU_ITEM](#places-administration-menu-item) | Global | A page that has its own item in the administration menu. |
| [ARTICLE_ABOVE_ACTIVITY_STREAM](#places-article-above-activity-stream) | Article | The area in an article above the activity stream. |
| [ARTICLE_BELOW_SUMMARY](#places-article-below-summary) | Article | The area in an article below the title. |
| [ARTICLE_OPTIONS_MENU_ITEM](#places-article-options-menu-item) | Article | An item in the article toolbar that invokes the widget. |
| [DASHBOARD_WIDGET](#places-dashboard-widget) | Global | The dashboard. |
| [HELPDESK_CHANNEL](#places-helpdesk-channel) | Project | An extra channel for tickets. This extension point is only available for helpdesk projects. |
| [ISSUE_ABOVE_ACTIVITY_STREAM](#places-issue-above-activity-stream) | Issue | The area in an issue above the activity stream. |
| [ISSUE_BELOW_SUMMARY](#places-issue-below-summary) | Issue | The area in an issue below the issue summary. |
| [ISSUE_FIELD_PANEL_FIRST](#places-issue-field-panel-first) | Issue | The area in an issue above the custom field panel. |
| [ISSUE_FIELD_PANEL_LAST](#places-issue-field-panel-last) | Issue | The area in an issue below the custom field panel. |
| [ISSUE_OPTIONS_MENU_ITEM](#places-issue-options-menu-item) | Issue | An item in the issue toolbar that invokes the widget. |
| [MAIN_MENU_ITEM](#places-main-menu-item) | Global | A separate application page that is accessible from the main navigation menu. |
| [MARKDOWN](#places-markdown) | Global | The area in a Markdown-formatted text. |
| [PROJECT_SETTINGS](#places-project-settings) | Project | A separate tab in the project settings. |
| [PROJECT_TAB](#places-project-tab) | Project | A separate tab on the project page. |
| [USER_CARD](#places-user-card) | User | The area in the user card that you see when you hover over the username in an issue or article. |
| [USER_PROFILE_SETTINGS](#places-user-profile-settings) | User | A separate tab in the user profile. |

## Register a Widget with the Host API

If you want your widget to send HTTP requests to YouTrack or communicate with it using any of the YouTrack APIs, add a script that registers the widget in YouTrack in the HTML code of the widget.

You need to register your app in YouTrack, for example, when sending alerts to YouTrack from the widget. Once you've registered the app, you can use the Host API to send alerts in YouTrack or invoke functions implemented as custom [HTTP handlers](apps-reference-http-handlers.html).

Here you can see an example of the registration script:

```HTML
<script type="module">
    const host = await YTApp.register();
    host.alert('Hello world');
</script>
```

For more details about the Host API, see [Host API](apps-host-api.html).

## Administration Menu Item

| Name | Description | Scope |
| --- | --- | --- |
| `ADMINISTRATION_MENU_ITEM` | This extension point lets you create a page that has its own item in the administration menu.   | Global |

This extension point supports widget guards. If the guard returns `false`, the item is hidden from the administration menu. For details, see [Global Full-Page Widgets](apps-widget-guards.html#global-widget-guards).

By default, YouTrack shows the page header above widgets that use this extension point. To hide the header, set the widget's `showHeader` field to `false` in the [app manifest](app-manifest.html#app-manifest-widgets).

![A menu item for a widget that adds an administration page.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-administration-page-menu-item.png)

![An example of a widget that adds a page to the administration section of YouTrack.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-administration-page.png)

## Article above Activity Stream

| Name | Description | Scope |
| --- | --- | --- |
| `ARTICLE_ABOVE_ACTIVITY_STREAM` | This extension point lets you add a custom widget to the area in an article above the activity stream.   | Article |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in the article. For details, see [Article](apps-widget-guards.html#article-guards).

![An example of a widget that appears above the activity stream in an article.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-article-above-activity.png)

## Article Below Title

| Name | Description | Scope |
| --- | --- | --- |
| `ARTICLE_BELOW_SUMMARY` | This extension point lets you add a custom widget to the area in an article below the title.   | Article |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in the article. For details, see [Article](apps-widget-guards.html#article-guards).

![An example of a widget that appears below the article title.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-article-below-summary.png)

## Article Options Menu Item

| Name | Description | Scope |
| --- | --- | --- |
| `ARTICLE_OPTIONS_MENU_ITEM` | This extension point lets you add an item to the option menu in an article. When a user selects this option, the custom widget is displayed.   | Article |

This extension point supports widget guards. If the guard returns `false`, the item is hidden from the article option menu. For details, see [Article](apps-widget-guards.html#article-guards).

![An example of an app that adds a custom item to the option menu in an article.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-article-toolbar-item.png)

## Dashboard Widget

| Name | Description | Scope |
| --- | --- | --- |
| `DASHBOARD_WIDGET` | A widget that can be displayed on a dashboard.     Apps that use this extension point generate a special embedding component each time its widgets are displayed on a dashboard. This component is supported by a more extensive `CustomWidgetAPILayer` API that stores the data the widget displays in these locations. For more information about this API, see [Custom Widget API Reference](apps-host-api.html#custom-widget-api-reference).    | Global |

![An example of a widget that can be displayed on a dashboard.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-dashboard-widget.png)

## Helpdesk Channel

| Name | Description | Scope |
| --- | --- | --- |
| `HELPDESK_CHANNEL` | This extension point lets you create an extra channel for creating helpdesk tickets. It is only available for helpdesk projects.   | Project |

This extension point supports widget guards. If the guard returns `false`, the channel is hidden in the project. For details, see [Project](apps-widget-guards.html#project-guards).

![An example of a widget that creates a custom helpdesk channel.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-ticket-channel-page.png)

## Issue above Activity Stream

| Name | Description | Scope |
| --- | --- | --- |
| `ISSUE_ABOVE_ACTIVITY_STREAM` | This extension point lets you add a custom widget to the area in an issue above the activity stream.   | Issue |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in the issue. For details, see [Issue](apps-widget-guards.html#issue-guards).

![An example of a custom widget in an issue above the activity stream.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-issue-above-activity.png)

## Issue below Summary

| Name | Description | Scope |
| --- | --- | --- |
| `ISSUE_BELOW_SUMMARY` | This extension point lets you add a custom widget to the area in an issue below the issue summary.   | Issue |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in the issue. For details, see [Issue](apps-widget-guards.html#issue-guards).

![An example of a custom widget in an issue below the summary.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-issue-main-area.png)

## Issue Field Panel First

| Name | Description | Scope |
| --- | --- | --- |
| `ISSUE_FIELD_PANEL_FIRST` | This extension point lets you add a custom widget to the area in an issue above the custom field panel.   | Issue |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in the issue. For details, see [Issue](apps-widget-guards.html#issue-guards).

![An example of a custom widget shown in the area above the custom field panel.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-issue-sidebar-top.png)

## Issue Field Panel Last

| Name | Description | Scope |
| --- | --- | --- |
| `ISSUE_FIELD_PANEL_LAST` | This extension point lets you add a custom widget to the area in an issue below the custom field panel.   | Issue |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in the issue. For details, see [Issue](apps-widget-guards.html#issue-guards).

![An example of a custom widget shown in the area below the custom field panel.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-issue-sidebar.png)

## Issue Options Menu Item

| Name | Description | Scope |
| --- | --- | --- |
| `ISSUE_OPTIONS_MENU_ITEM` | This extension point lets you add an item to the option menu in an issue. When a user selects this option, the custom widget is displayed.   | Issue |

This extension point supports widget guards. If the guard returns `false`, the item is hidden from the issue option menu. For details, see [Issue](apps-widget-guards.html#issue-guards).

![An example of an app that adds a custom action to the option menu in an issue.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-issue-toolbar-item.png)

## Main Menu Item

| Name | Description | Scope |
| --- | --- | --- |
| `MAIN_MENU_ITEM` | This extension point lets you add a dedicated page to YouTrack that is accessible from the main menu.   | Global |

This extension point supports widget guards. If the guard returns `false`, the item is hidden from the main menu. For details, see [Global Full-Page Widgets](apps-widget-guards.html#global-widget-guards).

By default, YouTrack shows the page header above widgets that use this extension point. To hide the header, set the widget's `showHeader` field to `false` in the [app manifest](app-manifest.html#app-manifest-widgets).

![The header menu item for an app that uses this extension point.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-page-header-menu-item.png)

![An example of a custom widget that is accessible from the main menu.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-page.png)

## Markdown

| Name | Description | Scope |
| --- | --- | --- |
| `MARKDOWN` | A custom widget that can be used to embed content in areas that support rich text. These widgets can be embedded in issue descriptions, knowledge base articles, and comments in issues, tickets, and articles.     Despite the name of this extension point, this widget can embed content when editing in Visual mode as well as Markdown.     Apps that use this extension point generate a special embedding component each time its widgets are inserted into a text field. This component is supported by a more extensive `CustomWidgetAPILayer` API that stores the data the widget displays in these locations. For more information about this API, see [Custom Widget API Reference](apps-host-api.html#custom-widget-api-reference).    | Global |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in Markdown-formatted text and isn't available for embedding. For details, see [Markdown Widgets](apps-widget-guards.html#markdown-guards).

![An example of a custom widget that displays embedded content.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-markdown.png)

## Project Settings

| Name | Description | Scope |
| --- | --- | --- |
| `PROJECT_SETTINGS` | This extension point lets you create a separate tab in the project settings.   | Project |

This extension point supports widget guards. If the guard returns `false`, the tab is hidden from the project settings. For details, see [Project](apps-widget-guards.html#project-guards).

![An example of a widget that adds a dedicated tab to the project settings.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-project-administration-area.png)

## Project Tab

| Name | Description | Scope |
| --- | --- | --- |
| `PROJECT_TAB` | This extension point lets you create a separate tab on the project page.   | Project |

This extension point adds an item to the project sidebar. Users can open the widget from a project where the app is attached and the widget is active.

This extension point supports widget guards. If the guard returns `false`, the item is hidden from the project sidebar. For details, see [Project](apps-widget-guards.html#project-guards).

![An example of a widget that adds a dedicated tab to the project page.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-project-tab.png)

## User Card

| Name | Description | Scope |
| --- | --- | --- |
| `USER_CARD` | This extension point lets you customize the area in the user card that you see when you hover over a username in an issue, ticket, or article.    | User |

This extension point supports widget guards. If the guard returns `false`, the widget is hidden in the user card. For details, see [User](apps-widget-guards.html#user-guards).

![An example of widget that displays information on user cards.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-user-card.png)

## User Profile Settings

| Name | Description | Scope |
| --- | --- | --- |
| `USER_PROFILE_SETTINGS` | This extension point lets you create a separate tab in the user profile.   | User |

Use this extension point when your app needs to show a dedicated view for a user, for example, app-specific profile settings or profile data managed by the app.

> **Note: Storing User-Specific App Data**
> This extension point embeds a widget in the user profile. It doesn't create native fields in the YouTrack user profile. To store app-owned values for users, declare extension properties for the `User` entity. For details, see [Extension Properties](apps-extension-properties.html).

A widget that uses this extension point has the user entity as its context. After registering the widget with the Host API, you can use `YTApp.entity` to read the user profile from frontend code. To call a user-scoped HTTP handler for this user, call `host.fetchApp()` with `scope: true`. The handler receives this user as `ctx.user`.

Here is an example of a widget declaration for this extension point:

```JSON
"widgets": [
  {
    "key": "profile-settings",
    "name": "Profile Settings",
    "extensionPoint": "USER_PROFILE_SETTINGS",
    "indexPath": "profile-settings/index.html"
  }
]
```

Here is an example of the frontend code that reads the user profile and calls a scoped HTTP handler:

```JAVASCRIPT
const host = await YTApp.register();
const user = await host.fetchYouTrack(`users/${YTApp.entity.id}?fields=id,login,name`);
const profileSettings = await host.fetchApp('backend/profileSettings', {method: 'GET', scope: true});
```

The scoped HTTP handler receives the same user as `ctx.user`. This handler can read or update app-owned values stored in user extension properties. This example assumes that the app declares a `User` extension property named `profilePreferences`:

```JAVASCRIPT
exports.httpHandler = {
  endpoints: [
    {
      scope: 'user',
      method: 'GET',
      path: 'profileSettings',
      handle: function(ctx) {
        ctx.response.json({
          user: {
            id: ctx.user.id,
            login: ctx.user.login
          },
          preferences: ctx.user.extensionProperties.profilePreferences || '{}'
        });
      }
    }
  ]
};
```

This extension point supports widget guards. If the guard returns `false`, the tab is hidden from the user profile. For details, see [User](apps-widget-guards.html#user-guards).

![An example of a widget that adds a dedicated tab to the user profile.](https://resources.jetbrains.com.cn/help/img/youtrack/apps-places-user-profile-area.png)