API docs

What problem does this solve?

The mentions pattern exists as a way to notify and include a person or group in the context of your text. Mentioning a user sends them an email (or in-app notification if applicable) notifying them that they have been mentioned with supporting context. The rendered style for a mention is clickable and should link through to more information about that user on a dedicated profile page. Users are suggested based on the text entered.


Rendered mention of a user

Text color is Blue when linkable and charcoal when not – see colors.

Mentions pattern

Triggering the mentions dialog

Mentions pattern

Spinner when querying the database

Add a medium spinner centered inside the triggered dialog. Maintain the height of the dialog to avoid it jumping when data is returned.

Mentions pattern

Rendered mention of you

Background color is blue with light grey text.

Mentions pattern

Mentions with groups and teams

Add a separator if the results returned show users and groups of users.

Mentions pattern

Removing a mention

Backspacing will highlight the border color to gray #999. The second backspace will remove the Mention label.

Mentions pattern

When and how to use this pattern

  • Used in any piece of user-generated content
  • The @ sign triggers an inline dialog
  • Cache locally the last 5 users you have mentioned to quickly access them again
  • If no users have been cached, show 5 alphabetically
  • Use a spinner in the list of users when querying the database for users (see example). It is important that the actual inline dialog appears instantaneously, while its content can be loaded in when available
  • Keyboard navigation to move up and down the user list
  • The visual style of the mentions label for yourself should be different from mentions for other users. This allows for easy recognition of where you have been mentioned (see example above)
  • Users, groups and teams can be mentioned and triggered in the same dialog
  • Groups have a generic avatar in the list. If there are users and groups matching the same query then the users are displayed at the top while groups remain at the bottom with a separating line between them (see example)
  • The first user or group is always selected by default when the user starts typing
  • After a user or group has been selected from the list, the label will render inline
  • The width of the mentions dialog should be 350px wide with truncaton on the email address if needed
  • As the user types a person or group name, the matching letters should be bolded in the mentions dialog
  • Use 24px avatars in the mentions dialog with 5px padding around the containing elements

What happens if…

  • …I want to edit the text inside the label: Clicking on the label can trigger an inline dialog containing an edit link action
  • …there is not enough space in the viewport for the inline dialog to display below the trigger: Invert the inline dialog to display above the @ mention
  • …the mentioned user or group doesn't have a profile page to link to: If the text can't be linked then use the charcoal #333 color
  • …the mentioned user needs to removed: Pressing backspace would first highlight the label border and the second backspace would remove the whole label. To re-trigger the mention dialog the user will type the @ sign again
  • …I want to use mentions in a textarea: The following guidelines apply:
    • Trigger a mention with an '@' symbol as above
    • While there is at least one valid match, continue matching for as many characters (including spaces) as the user types
    • On the character which results in no valid match, allow the user to continue typing up to 6 characters while remaining in the mention - on the first character past 6, exit the mention
    • Pressing 'Esc' at any point also exits the mention
    • Whenever the mention query changes (e.g. user pressing backspace or user typing), show updated suggestions