Extension Points

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.

Extension Point	Scope	Description
ADMINISTRATION_MENU_ITEM	Global	A page that has its own item in the administration menu.
ARTICLE_ABOVE_ACTIVITY_STREAM	Article	The area in an article above the activity stream.
ARTICLE_BELOW_SUMMARY	Article	The area in an article below the title.
ARTICLE_OPTIONS_MENU_ITEM	Article	An item in the article toolbar that invokes the widget.
DASHBOARD_WIDGET	Global	The dashboard.
HELPDESK_CHANNEL	Project	An extra channel for tickets. This extension point is only available for helpdesk projects.
ISSUE_ABOVE_ACTIVITY_STREAM	Issue	The area in an issue above the activity stream.
ISSUE_BELOW_SUMMARY	Issue	The area in an issue below the issue summary.
ISSUE_FIELD_PANEL_FIRST	Issue	The area in an issue above the custom field panel.
ISSUE_FIELD_PANEL_LAST	Issue	The area in an issue below the custom field panel.
ISSUE_OPTIONS_MENU_ITEM	Issue	An item in the issue toolbar that invokes the widget.
MAIN_MENU_ITEM	Global	A separate application page with a menu item in the header.
MARKDOWN	Global	The area in a Markdown-formatted text.
PROJECT_SETTINGS	Project	A separate tab in the project settings.
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	User	A separate tab in the user profile.

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.

Here you can see an example of the registration script:

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

For more details about the Host API, see Host API.

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

A menu item for a widget that adds an administration page.

An example of a widget that adds a page to the administration section of YouTrack.

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

An example of a widget that appears above the activity stream in an article.

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

An example of a widget that appears below the article title.

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

An example of an app that adds a custom item to the option menu in an article.

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 .	Global

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 .

Global

An example of a widget that can be displayed on a dashboard.

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

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

An example of a custom widget in an issue above the activity stream.

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

An example of a custom widget in an issue below the summary.

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

An example of a custom widget shown in the area above the custom field panel.

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

An example of a custom widget shown in the area below the custom field panel.

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

An example of an app that adds a custom action to the option menu in an issue.

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

The header menu item for an app that uses this extension point.

An example of a custom widget that is accessible from the main menu.

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 .	Global

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 .

Global

An example of a custom widget that displays embedded content.

Project Settings

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

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

User Profile Settings

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

Last modified: 7 November 2024

Developer Portal for YouTrack and Hub Help

Extension Points

Register a Widget with the Host API

Administration Menu Item