Conditional Widgets | Developer Portal for YouTrack and Hub Documentation

Some widgets only need to appear in certain conditions. You may want to display a widget only when specific requirements are met and hide them otherwise. Widget guard conditions help you with such scenarios.

To define a condition for showing a widget, add a guard function to the widget description in the app manifest.

A widget guard is a JavaScript function that takes a YouTrack entity as its argument and lets you check its properties. For the widget to be shown to the user, such a function must return a value that evaluates to true.

The argument of a widget guard function is the YouTrack entity corresponding to the extension point of the widget. To view the mapping between extension points and YouTrack entities, see Guard Entity Reference.

Guard functions are synchronous. They cannot return promises or use the async/await syntax. Guard functions are executed in an isolated sandbox and can't refer to any resources except function arguments.

Sample Conditional Widget

Here is an example of a conditional widget with a guard function. In the manifest, add a guard property to the widget description.

In this example, the guard condition checks whether the value of the State field in an issue equals to Open. If it's the case, the widget appears in the issue.

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

Guard Entity Reference

Here is the list of YouTrack entities that guard functions take as arguments, along with the mapping between them and widget extension points. You can use these entities and their properties to form a JavaScript guard function and define the condition.

Issue

Property

Type

Description

id

String

The ID of the issue.

summary

String

The summary of the issue.

fields

Fields

The set of custom fields that are used in the issue.

For each custom field, you can use the following field properties:

Name

Type

Description

name

String

The name of the field.

type

String

The type of the field.

Possible values:

datetime
date
number
string
text
enum
user
group
period
sla

value

String

Number

Boolean

The value of the field.

draft

Boolean

True when the issue is still a draft, and false when the issue is already created.

isEditing

Boolean

True when the issue is being edited, and false in issue view mode.

The following extension points take issue entity as their guard function argument:

ISSUE_ABOVE_ACTIVITY_STREAM
ISSUE_BELOW_SUMMARY
ISSUE_FIELD_PANEL_LAST
ISSUE_FIELD_PANEL_FIRST
ISSUE_OPTIONS_MENU_ITEM

Article

Property	Type	Description
`id`	String	The ID of the article.
`summary`	String	The title of the article.
`draft`	Boolean	`True` when the article is still a draft, and `false` when the article is already created.
`isEditing`	Boolean	`True` when the article is being edited, and `false` in article view mode.

The following extension points take article entity as their guard function argument:

ARTICLE_OPTIONS_MENU_ITEM
ARTICLE_BELOW_SUMMARY
ARTICLE_ABOVE_ACTIVITY_STREAM

Ticket

Property	Type	Description
`id`	String	The ID of the ticket.
`summary`	String	The summary of the ticket.
`fields`	Fields	The set of custom fields that are used in the ticket.
`isEditing`	Boolean	`True` when the ticket is being edited, and `false` in ticket view mode.

The following extension points take ticket entity as their guard function argument:

ISSUE_ABOVE_ACTIVITY_STREAM
ISSUE_BELOW_SUMMARY
ISSUE_FIELD_PANEL_LAST
ISSUE_FIELD_PANEL_FIRST
ISSUE_OPTIONS_MENU_ITEM

Project

Property	Type	Description
`id`	String	The ID of the project.
`key`	String	The key of the project.

The following extension points take project entity as their guard function argument:

HELPDESK_CHANNEL
PROJECT_SETTINGS

User

Property	Type	Description
`id`	String	The ID of the user.
`login`	String	The user login.

The following extension points take user entity as their guard function argument:

USER_CARD
USER_PROFILE_SETTINGS

21 November 2025