Conditional Widgets

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 context object as its argument and lets you check its properties. For the widget to be shown to the user, such a function must return true. When the function returns false, the widget is hidden.

The context object always contains the current user as me. For extension points that are evaluated in the context of a specific YouTrack entity, the context object also contains entity. 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. If a guard function returns a value that isn't boolean, or throws an error, the widget is hidden.

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"]
                    }
                  ]
        

Guards for Global and Markdown Widgets

Global full-page widgets and Markdown widgets support guard functions, but each type of widget uses a different guard context. Use the following examples to choose the right context properties for each extension point.

Global full-page extension points, such as MAIN_MENU_ITEM and ADMINISTRATION_MENU_ITEM, don't have a host entity. Guards for these extension points can check properties of the current user in the me object, for example me.userType, me.login, or me.name. When the guard returns false, YouTrack hides the corresponding item from the main menu or administration menu.

                "widgets": [
                  {
                    "key": "team-report",
                    "name": "Team Report",
                    "description": "A report page for standard users and agents",
                    "guard": "({me}) => me.userType !== 'reporter'",
                    "extensionPoint": "MAIN_MENU_ITEM",
                    "indexPath": "team-report/index.html",
                    "iconPath": "team-report/icon.png"
                  }
                ]
            

Markdown Widgets

Markdown widgets can also use guards. For these widgets, the entity argument depends on where the text with the embedded widget is displayed. For example, the entity can be an issue, a helpdesk ticket, or an article.

                "widgets": [
                  {
                    "key": "issue-context-card",
                    "name": "Issue Context Card",
                    "description": "Shows extra information in issue text",
                    "guard": "({entity, me}) => me.userType !== 'reporter' && entity?.type === 'issue' && !entity.isResolved",
                    "extensionPoint": "MARKDOWN",
                    "indexPath": "issue-context-card/index.html",
                    "settingsSchemaPath": "issue-context-card/settings.json",
                    "defaultDimensions": {
                      "width": "100%",
                      "height": "120px"
                    }
                  }
                ]
            

Guard Entity Reference

Here is the list of YouTrack entities that guard functions can 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.

Context Object

Property	Type	Description
`me`	User	The current YouTrack user. This property is available for guards in all supported extension points.
`entity`	Issue Ticket Article Project User	The YouTrack entity where the widget is displayed. This property is available for entity-related extension points. For global full-page extension points, use `me` instead.

Property

Type

Description

me

User

The current YouTrack user. This property is available for guards in all supported extension points.

entity

Issue

Ticket

Article

Project

User

The YouTrack entity where the widget is displayed.

This property is available for entity-related extension points. For global full-page extension points, use me instead.

Issue

Property

Type

Description

id

String

The ID of the issue.

type

String

The entity type. The value is 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.

isResolved

Boolean

true when the issue is resolved, and false when the issue is unresolved.

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.
`type`	String	The entity type. The value is `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.
`type`	String	The entity type. The value is `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.
`isResolved`	Boolean	`true` when the ticket is resolved, and `false` when the ticket is unresolved.

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.
`type`	String	The entity type. The value is `project`.
`key`	String	The key of the project.

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

HELPDESK_CHANNEL
PROJECT_SETTINGS
PROJECT_TAB

User

Property	Type	Description
`id`	String	The ID of the user.
`type`	String	The entity type. The value is `user`.
`login`	String	The user login.
`name`	String	The user display name.
`avatarUrl`	String	The URL of the user avatar.
`userType`	String	The type of the user account. Possible values: `standard` `agent` `reporter`

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

USER_CARD
USER_PROFILE_SETTINGS

The following extension points support guards, but don't take entity as their guard function argument. Use the me object to check properties of the current user and show or hide these widgets based on those values:

ADMINISTRATION_MENU_ITEM
MAIN_MENU_ITEM

Markdown Widgets

The MARKDOWN extension point supports guards. When a Markdown widget is evaluated in the context of a YouTrack entity, the guard function receives this entity as entity. Depending on where the embedded text is displayed, this value can be an issue, a helpdesk ticket, or an article.

When writing a guard for a Markdown widget, check entity.type before reading entity-specific properties.

24 June 2026

Developer Portal for YouTrack and Hub Help

Sample Conditional Widget

Guards for Global and Markdown Widgets

Global Full-Page Widgets

Markdown Widgets

Guard Entity Reference

Context Object

Issue

Article

Ticket

Project

User

Global Full-Page Widgets

Markdown Widgets