UI elements and interaction Edit

Highlight: Emphasize on the task to be accomplished, rather than how the user should interact with the UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. element. Format UI element names in bold, and use appropriate nouns and verbs to describe how to interact with them.

Emphasize the task

When writing about interactions involving the user interface (UI), emphasize on the task to be accomplished, rather than how the user should interact with the UI element. By avoiding reference to UI elements, you help the reader understand the purpose of an instruction and avoid confusion due to additional external elements.

However, be watchful of the context and the reader demographic and how that influences your documentation; sometimes the objective of a procedure is to guide readers through elements on a page.

Examples

Not recommended: Click the PUBLISH button.

Not recommended: Click the Publish button.

Not recommended: Click the “Publish” button.

Recommended: Click Publish.

Recommended (consider context): Publish the post.

Not recommended: Click the arrow indicator to open the Time zone options section.

Recommended: To open the Time zone options section, click the dropdown arrow.

Recommended (consider context): Open the Time zone options section.

Top ↑

Formatting UI element names

When referring to a UI element by name, format the name in bold using the <b> element in HTML or ** in Markdown. UI element names include those of buttons, windows, menus, dialogs, or any other element in the page or console that has a visible name. Don’t use code font for UI element names, unless it is an element that requires code font; in which case use both code font and bold text formatting. Capitalize UI element names as per document context, but if the element names are inconsistent, use sentence-case capitalization.

Don’t apply bold formatting to an official feature name or product name, except when it directly refers to an element in the page that uses the name (such as a window title or button name).

Examples

Not recommended: In the Appearance section, select “Themes” and then click the “Add New” button.

Recommended: In the Appearance section, select the Themes option and then click Add New.

Not recommended: Click DOWNLOAD.

Recommended: Click Download.

Top ↑

Pressing and typing keyboard keys

To express a key or a combination of keys on a keyboard to be pressed by the user, use the <kbd> element. To refer to a keyboard shortcut, use either keyboard shortcut or key combination. To refer to the action of pressing a key or combination, use the verb press. To refer to the action of inputting a key or combination, use the verbs type, enter, or input.

Examples

Recommended: Press <kbd>Control+K</kbd>.

The text renders as follows:
Recommended: Press Control+K.

If you’re using non-HTML markup, use monospace text formatting, which is how <kbd> renders. In Markdown, enclose the key name in backticks (`).

To express a key that the user has to type to enter that key’s value as text input, use the <code> element instead of the <kbd> element. For more information, see Code font.

To refer to a keyboard key, use the key’s name. If the key’s name is ambiguous, use the form the KEY_NAME key.

Examples

Recommended: Press Esc.

Recommended: Press the Esc key.

Don’t abbreviate the names of modifier keys such as Control, Shift, Command, and Option. Spell out the complete key names and don’t use their symbols. To refer to a key combination that uses a modifier key, use the form MODIFIER_KEY+KEY_NAME.

Examples

Not recommended: Press Ctrl+T.

Recommended: Press Control+T.

Not recommended: Press ⌘+T.

Recommended: Press Command+T.

In most cases, to accommodate both Windows and Mac users, insert the Mac shortcut in parentheses after the Windows shortcut.

Examples

Not recommended: To redo, press Ctrl+Y (⌘+Y).

Recommended: To redo, press Control+Y (or Command+Y on Mac).

To refer to a key or combination that uses the Shift key, use the form MODIFIER_KEY+Shift+KEY_NAME.

Examples

Recommended: Press Control+Shift+T.

Recommended: Press Alt+Shift+R.

In general, use uppercase capitalization for character keys.

Spell out the names of characters that could be ambiguous or confusing in a keyboard shortcut, such as comma, hyphen, period, and plus.

Examples

Not recommended: Press Control++.

Recommended: Press Control+Plus.

Top ↑

Terminology and usage

There can be multiple elements in a user interface. Emphasize the task and focus on the feature and functionality of the UI element, rather than focusing on the UI element itself.

Examples

Recommended: Go to Plugins > Installed Plugins.

Recommended: In the Plugins section, select Installed Plugins.

Following are the terminology and word usage when referring to UI elements:

Top ↑

Window, page, dialog, and view

A window is the complete application window in a desktop environment. A window can also refer to adaptive application elements that can be opened and closed. To refer to a window, use the form the LABEL_NAME window.

Examples

Not recommended: On the Publish page, click Save.

Recommended: In the Publish window, click Save.

Generally, a page is the shortened version of the word webpage. To refer to a page, use the form the LABEL_NAME page.

Examples

Not recommended: On the Dashboard, go to the Updates window.

Recommended: On the Dashboard, go to the Updates page.

A dialog is a small window that appears in front of the window, but is separate from the main application window. To refer to a dialog, use the form the LABEL_NAME dialog.

Examples

Not recommended: In the Choose Image pop-up window, click Upload.

Recommended: In the Choose Image dialog, click Upload.

A view or a pane is a smaller section that is part of the application window. Generally, a view is adjacent to other UI elements and regions, and cannot be hidden, whereas a window is separate and can be hidden. To refer to a view, use the form the LABEL_NAME view.

Example

Recommended: In the Appearance view, click Typography.

When referring to windows, dialogs, and views, use the preposition in. Use on when referring to a page.

Examples

Recommended: In the Customize window, click Edit.

Recommended: On the Users page, click Add New.

Recommended: In the Delete WidgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. dialog, click Delete.

Recommended: In the Custom Menus view, click Primary Menu.

Top ↑

Button and icon

A button is a UI element that performs or initiates a specified action when clicked or tapped. To refer to a button, use the form the LABEL_NAME button.

Examples

Not recommended: Click the “Publish” button.

Recommended: Click Publish.

An icon is a image, sign, or symbol that depicts a function. An icon can also be a component of a button. To refer to a button with an icon, use the form the BUTTON_ICON LABEL_NAME button. If you are unsure of the name of the icon, inspect the element to use the aria-label attribute. For more information, see Using an aria-label.

Examples

Not recommended: Click the  icon.

Recommended: Click Search.

If a UI element name ends with an ellipsis (…), exclude the ellipsis.

Examples

Not recommended: Click Read more….

Recommended: Click Read more.

In general, avoid using directional language such as above, top, below, left-hand side, lower-right side in instructions to locate UI elements or other content. Directional language proves to be difficult for accessibility or for localization. If a particular UI element or other content is difficult to convey, include a screenshot or illustration.

Examples

Not recommended: On the upper-right part of the page, click the button with the checkmark.

Recommended: Click ✓ Publish.

Top ↑

A menu bar is a set of menus that is at the top of a desktop application window, such as File, Edit, or View. Each menu has a set of submenus or commands. To refer to a menu, use the form the LABEL_NAME menu. To refer to an item in the menu, use the form the LABEL_NAME command.

When combining multiple small actions into a single sequential step use angle brackets (>) to make simple sentences. If you use angle brackets, use the following guidelines:

  • Insert spaces around each angle bracket, with the space before the bracket being a nonbreaking space (&nbsp;).
  • Don’t use bold text formatting for each individual menu name. Instead, enclose the entire sequential step in a single bold element; for example, in HTML use <b>Settings > Media</b> and in Markdown, use **Settings > Media**.
  • Enclose the angle bracket with a <span> tag and add an aria-label attribute with and then text (<span aria-label="and then">></span>). Otherwise, some screen readers may skip over brackets or read > as greater than.

For more information, see Instructions with multiple actions.

Examples

Recommended (HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites.): Select <b>Edit&nbsp;<span aria-label="and then">></span> Text&nbsp;<span aria-label="and then">></span> Encoding</b>.

Recommended (Markdown): Select **Edit&nbsp;<span aria-label="and then">></span> Text <span aria-label="and then">></span> Encoding**.

This renders as: Select Edit > Text > Encoding.
A screen reader interprets this as Select Edit and then Text and then Encoding.

Use this format only for combining multiple small actions into a single sequential step; for example, In the Settings menu click Media. Use this format only for menu items; don’t use it to express a combination of different UI elements.

Examples

Not recommended: Select Edit > Appearance > Themes > + > Activate.

Recommended: Select Edit > Appearance, and select Themes. Click on Add New and click Activate.

Top ↑

Toolbar

A toolbar is a set of buttons for the most frequently used user features. To refer to a toolbar, use the form the LABEL_NAME toolbar.

Example

Recommended: In the Admin toolbar, click Profile.

Top ↑

Tab

A tab is a navigation element that looks like a file tab. To refer to a tab, use the form the LABEL_NAME tab.

Example

Recommended: Select Settings > Preferences, and then click the Edit tab.

Top ↑

Text box

A text box or a text field is a box that the user can input or type in. To refer to a text box, use the form the LABEL_NAME box. Use code formatting for the text that the user inputs using the <code> element in HTML, backticks (`) in Markdown, or a monospace font in other markup.

Examples

Recommended: In the Link box, enter your sitemap link.

Recommended: In the Mail server box, enter the port as 110.

Recommended: In the Alt text box, enter a brief image description without exceeding 100 characters.

Top ↑

A dropdown list or a list box is a UI element that provides a list of items for the user to choose from. To refer to a dropdown list, use the form the LABEL_NAME dropdown list or the LABEL_NAME box depending upon the context.

Example

Recommended: In the Default page dropdown list, select Homepage.

A combo box is a combination of a text box and a dropdown list. To refer to a list box, use the form the LABEL_NAME box. To refer to the action of inputting a value into a combo box, use the verbs enter, type, or select.

Example

Recommended: In the Post box, type or select the post type you want to use.

A spin box is a UI element that lets the user choose a value — a numerical value in most cases — by clicking arrows or by typing. To refer to a spin box, use the form the LABEL_NAME box. To refer to the action of entering a value into a spin box, use the verb enter.

Example

Recommended: In the Font Size box, enter a font size.

Top ↑

Expander

An expander arrow is a UI element that is used to expand or collapse a section of navigation or content. Avoid referring to expander arrows in documentation. If you have to refer to them, use the terms expander arrow and expandable section.

Example

Recommended: To expand the Advanced options section, click the expander arrow.

Top ↑

Checkbox

A checkbox is a box that indicates whether a particular value is selected or not. To refer to a checkbox, use the form the LABEL_NAME checkbox. Be cautious while using the verb check, which can be ambiguous. Use select instead.

Examples

Recommended: Select the Search engine visibility checkbox.

Recommended: Clear the Crop thumbnail checkbox.

Top ↑

Radio button

A radio button is a button used to choose one item from a group of mutually exclusive options. A radio button is used when only one item can be chosen from the list. To refer to a radio button, use the radio button’s label, or refer to the group of buttons by its label.

Examples

Recommended: Click Your latest posts.

Recommended: Select your preferred Post visibility.

Top ↑

Toggle button

A toggle button is a UI element that switches back and forth between on and off options or states. To refer to a toggle button, either use toggle as a noun or action verb.

Examples

Recommended: To deactivate, click the PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party toggle.

Recommended: You can toggle Fixed background in the BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Settings sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme..

Top ↑

Interaction verbs

For more information about interactive words to describe UI, see the Word list and usage dictionary.

To describe interactions with UI elements, use the following verbs:

Top ↑

Click

When the environment is presumably a desktop with a mouse, use click for most targets such as buttons, links, list items, and radio buttons.

Examples

Not recommended: Click on Save.

Recommended: Click Save.

Hyphenate left-click, right-click, and double-click.

When a click or tap action reveals a collapsed list, use the phrase click to expand or expand.

It’s acceptable to write click in when referring to a region that needs focus (for example, click in the window), but not when referring to a control or a link.

Top ↑

Select

Use select when referring to the action of the user selecting targets such as menu commands, checkboxes, items, and dropdown lists. Select can be use interchangeably instead of click or check in describing checkboxes and dropdown lists.

Examples

Recommended: In the Appearance section, select the Themes option and then click Add New.

Recommended: Select Edit > Text > Encoding.

Recommended: In the Plugins section, select Installed Plugins.

Top ↑

Select and hold

Use select and hold when referring to the action of the user selecting and holding a UI element. It’s acceptable to use right-click with select and hold when the instruction isn’t specific to touch devices.

Examples

Recommended: To pick multiple images, select and hold an image and choose the required images.

Recommended: On Windows devices, select and hold (or right-click) to open the context menu.

Top ↑

Enter, type

Use enter and type when referring to the action of the user entering text, or inserting a value.

Don’t use input as a verb.

Examples

Recommended: In the Post box, type or select the post type you want to use.

Recommended: In the Link box, enter your sitemap link.

Top ↑

Go to

Use go to when referring to the action of opening a menu, going to a website, webpage, a tab, or another place in the UI.

Example

Recommended: Go to Plugins > Installed Plugins.

Top ↑

Tap

When the environment is presumably a touch device, use tap for most targets such as buttons, links, list items, and radio buttons.

Example

Recommended: Tap Save.

Top ↑

Press

Use press when referring to a key or a key combination that performs or initiates a specified action when activated.

Example

Recommended: To redo, press Control+Y (or Command+Y on Mac).

Top ↑

Choose

Use choose when referring to the action of the user making a choice from multiple options, a list of items, or numerical values.

Example

Recommended: In the Font Size box, choose a font size.

Top ↑

Clear

Use clear when referring to the action of clearing a selection, usually from a checkbox.

Example

Recommended: Clear the Crop thumbnail checkbox.

Top ↑

Hold, hold the pointer over

When the environment is presumably a touch device, use hold and hold the pointer over in a desktop environment, when referring to the action of the user holding or hovering the pointer over a UI element, but not clicking the element. This action involves waiting for the UI element to react. To refer to the action of pointing the mouse pointer use point to. This action doesn’t imply a length of time waiting for the UI element to react to user action.

Don’t use hover, hover the pointer over, or mouse over.

Example

Recommended: On the Admin toolbar, hold the pointer over New.

Top ↑

Switch, turn on, turn off, enable

Use switch, turn on, turn off, and enable when referring to the action of turning a switch or toggle key on or off.

Examples

Sometimes okay: To turn on Fixed background follow these steps:

Recommended: You can toggle Fixed background in the BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Settings sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme..

Recommended: To enable full width, select the Site Width toggle button.

Recommended: To switch between fixed width and full width, use the Site Width toggle button.

Don’t use enable or allow to express an ability to do something. Use lets you instead.

Examples

Not recommended: The get request enables you to retrieve the data.

Not recommended: The get request allows you to retrieve the data.

Recommended: The get request lets you retrieve the data.

Top ↑

Move, drag

Use move and drag when referring to the action of moving or dragging a UI element from one place in the UI to the other. In most cases, move and drag are used for tiles, files, and folders. It is acceptable to use move or move through to describe moving around UI such as a window or page.

Examples

Recommended: Drag to upload items in the Media Uploader.

Recommended: Move the file to the Shared folder.

Top ↑

Open

Use open when referring to the action of opening targets such as apps, programs, files, folders, tabs and websites. Don’t use open for menus and commands.

Example

Recommended: Open Settings.

Top ↑

Close

Use close when referring to the action of closing targets such as apps, programs, files, folders, notifications, dialogs, tabs, and websites.

Example

Recommended: Close the Options tab.

Recommended: After uploading the image, close the Choose Image dialog.

Top ↑

Zoom

Use zoom, zoom in, and zoom out a when referring to the action of changing the magnification of a screen, window, or a page.

Example

Recommended: Zoom in to see more details in the figure.

Last updated: