Widgets

A widget is a custom object that you can embed in one of the dedicated extension points in the YouTrack UI. Each app can contain one or more widgets.

Sample Widget

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

Here is an example of a widget description in the app manifest:

            
                    "widgets": [
                        {
                        "key": "fields-first",
                        "name": "Sample Widget",
                        "description": "Optional description for the issue view widget",
                        "guard": "({entity}) => entity.fields.State?.value === 'Fixed'",
                        "extensionPoint": "ISSUE_FIELD_PANEL_FIRST",
                        "indexPath": "index.html",
                        "iconPath": "icon.png",
                        "settingsSchemaPath": "sample-widget-settings.json",
                        "permissions": ["READ_USER"]
                        }
                    ]
            
        

This sample widget is embedded in the custom field panel in issue view and appears when the issue is in the Fixed state.

The widget content is stored in the dedicated index.html file. Here is sample code for the widget content:

<!doctype html> <html> <head> <link rel="stylesheet" href="https://unpkg.com/@jetbrains/ring-ui-built@6/components/style.css"> <link rel="stylesheet" href="../index.css"> </head> <body class="plugin" style="padding: 0; overflow: hidden;"> <div id="root"> </div> <script type="module"> const host = await YTApp.register(); console.log('init cat widget', host) var viewportWidth = window.innerWidth || document.documentElement.clientWidth; var viewportHeight = window.innerHeight || document.documentElement.clientHeight; const img = document.createElement('img'); img.src = `https://cataas.com/cat?width=${viewportWidth}`; img.width = viewportWidth; img.height = viewportHeight; img.style = `object-fit: cover;`; document.getElementById('root').appendChild(img); img.onclick = () => { host.enterModalMode(); }; </script> </body> </html>

For more examples of widgets in different places in the UI, refer to Extension Points for Widgets.

A widget can be embedded in different places in the YouTrack UI, for example, in an issue, an article, or in the main menu. The particular place where a widget appears is defined by the extension point the widget is using.

For full reference on widget extension points, see Extension Points for Widgets.

Guards

If you want to show a widget only when some requirements are met and hide them otherwise, use guard conditions. To define a condition for showing a widget, add a guard function to the widget description in the app manifest.

Widget guards are Javascript functions that check various conditions related to YouTrack entities and their properties. For the widget to be shown, such function must return a value that evaluates to true.

Here is an example of a guard condition for showing a widget. This guard function checks if the issue is in the Fixed state and shows the widget only if this condition checks to true.

"guard": "({entity}) => entity.fields.State?.value === 'Fixed'"

For more details and reference on widget guards, see Conditional Widgets.

21 November 2025