# Link UI guidelines on using links. **Implementation:** [`ActionLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/ActionLink.kt), [`DropDownLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/DropDownLink.kt) ![A preview of link types: default, drop-down, and external.](link.png){width=706} ## When to use ### Navigation inside a window Use a regular link for navigation between pages of the same window. In the example bellow Manage scopes… opens another page in Settings for editing the values.
Correct A vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed by a 'Manage scopes…' link below. Incorrect A vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed 'Manage scopes' button below.
### Web resources Use an external link for navigation to web resources. See below for the [external link icon](#external-link-icon). ![Text 'Learn more about what is logged' with 'what is logged' as an external link with an arrow icon.](link_when_to_2.png){width=706} ### Secondary actions in packed UI areas Use a regular or [drop-down link](#drop-down-link) for secondary actions in packed or small UI areas. ![Build and run section with 'Modify options' drop-down link. Contains a Java SDK selector, a command line arguments selector, and a program arguments input.](link_when_to_4.png){width=706} ### Secondary actions in a tree or table #### Some items can be changed Use a link as a secondary action for some items of a tree or table. ![A tree with a checkbox and four dependent controls, and links 'Set…' in the first and the fourth control](link_when_to_5.png){width=706} #### All items can be changed

If a link in every tree or table line has meaningful formatting, leave it.

For example, links in the Push Commits window help understand the relation between them: [remote repository] : [branch]; moving these links elsewhere would break this meaning.

Links in the Push Commits window 'origin : master' ## When not to use ### Primary actions Use a [button](button.topic) or a [drop down list](drop_down.md) for primary actions. These controls can be selected from the keyboard and are bigger and easier to click.
Correct The Commit Message input with primary and secondary actions as buttons. Incorrect The Commit Message input with primary and secondary actions as links.
### Secondary actions in a tree or table {id="secondary-actions-not-to-use"} #### Editable items

When all items can be changed, add an icon button to a toolbar.

Correct Table with a toolbar with icon-buttons Incorrect Table with a link 'Edit…' in every row
#### List of choices

For a list of choices, add a separate table column of drop-down cells (see Table).

Correct Table with a toolbar with icon-buttons Incorrect Table with a link 'Edit…' in every row
### Simple UI Use a [button](button.topic) or a [drop down list](drop_down.md) when a UI is not constrained. These controls can be selected from the keyboard and are bigger and easier to click.
Correct A stack of controls with a button 'Edit' following one of the controls.
Incorrect A stack of controls with a link 'Edit' following one of the controls.
## How to use ### Writing guidelines #### Use sentence capitalization Follow the [sentence capilaziation](capitalization.md#sentence) guideline.
Correct A 'Modify options' drod-down with the sentence style capitalization. Incorrect A 'Modify Options' drod-down with the title style capitalization.
#### Ellipsis Add an ellipsis to a link if it opens another UI area where input is possible. See examples for the [Button](button.topic).
Correct A vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed by a 'Manage scopes…' link below. The link has an ellipsis in the end. Incorrect Vertical list of three options: 'Non-Project Files', 'Problems', and 'Production', followed by a 'Manage scopes' link below. The link doesn't have an ellipsis in the end.
#### Wording Do not use words like navigate or click here. A link already implies navigation or clicking.
Correct Link 'Proxy settings…'. Incorrect Link 'Navigate to general proxy settings'.
Correct Link 'Download drivers…'. Incorrect Text reading 'Click here to download drivers' where 'here' is a link.
#### Make it informative When possible, replace Learn more and other generic phrases with more informative ones.
Correct Link 'How to use Closure Linter'. Incorrect Link 'Learn more'.
### Link as a part of text A link can be a part of a checkbox or radio button label or of any stand-alone text, like the text in an [empty state](empty_state.md) or in [context help](context_help.md): ![Checkbox 'Use console font instead of the default font' where 'deafult font' is a link.](link_how_to_6.png){width=706} Make a link the minimum phrase that is enough to understand what will happen without reading the whole text:
Correct Text reading 'Learn more about what is logged' where 'what is logged' is a link. Incorrect Link 'Learn more about what is logged'.
### External link icon Add the arrow icon for an external link. The icon shows that the user will switch to a browser and lose the current context. ![Text 'Learn more about what is logged' where 'what is logged' is an external link with the external link icon.](link_how_to_8.png){width=706} ```kotlin val externalLink = ActionLink("External link") { BrowserUtil.browse("https://www.jetbrains.com") }.apply { setExternalLinkIcon() } ``` ```java ActionLink externalLink = new ActionLink( "External link", event -> BrowserUtil.browse("https://www.jetbrains.com") ); externalLink.setExternalLinkIcon(); ``` ### Help icon Use the help icon in links in [empty states](empty_state.md) to indicate that this is an external help resource. The arrow icon in this case is unnecessary.
Correct Empty state in the Database tool window with an explanation text and a help source link 'Defining a database' with the help icon. Incorrect Empty state in the Database tool window with an explanation text and an external link 'Defining a database' with the external link icon.
### Drop-down link Drop-down links show a context menu or a popup. To implement, use [`DropDownLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/DropDownLink.kt). ![Control 'Changes from 2 commits' where '2 commits' is a drop-down link opening a list of all commits](link_dropdown.png){width=706} ## Placement * For default links follow [layout of buttons and links](layout.md#buttons-and-links). * For drop-down links follow [layout of labeled controls](layout.md#labeled-input-controls). ## Built-in behavior A focused link is activated from the keyboard with Space.