UX Patterns Guide
UI + UX Collaboration And Social Interaction established

Mentions

Provide inline mention insertion with scoped suggestions, stable recipient IDs, visible recipient type, ambiguity resolution, permission checks, audience warnings, notification routing, preference-aware delivery, and direct return links to the mention context.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • Composed content needs to target people or groups inline.
  • The product needs recipient-specific notifications, attention routing, action items, or searchable references from within comments, messages, documents, issues, or threads.
  • The sender must see and resolve access, ambiguity, or broad-audience effects before posting.
  • Recipients need direct return to the exact location where they were mentioned.

Avoid when

  • The user is selecting a structured owner, assignee, approver, or recipient field outside written content.
  • The surface is only an inbox of already-delivered notifications.
  • The product cannot preserve stable recipient IDs, access checks, or notification routing.
  • A broad broadcast or emergency alert needs a separate governed workflow rather than inline prose.

Problem it prevents

Collaboration breaks when inline @ references are treated as decorative text, notify the wrong audience, ignore access boundaries, fail to disambiguate similar names, or send recipients to a generic page instead of the exact context.

Test the behavior

Open the interactive example when you need it

The full lab is intentionally loaded on request. That keeps this reading page fast while preserving the strong and weak states, keyboard checks, and failure scenarios.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Mentions in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

Users are composing messages, comments, documents, tasks, issues, pull requests, notes, tickets, or thread replies and need to draw attention to specific people or groups.

Pattern promise

Provide inline mention insertion with scoped suggestions, stable recipient IDs, visible recipient type, ambiguity resolution, permission checks, audience warnings, notification routing, preference-aware delivery, and direct return links to the mention context.

Required state

Empty composer, @ trigger, loading suggestions, no results, and filtered suggestions.

Recovery path

The UI highlights @text but stores no recipient ID.

Access contract

Expose the suggestion list as a labelled popup tied to the editor and announce the number of available mention targets.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A comment composer opens a suggestion list after @, shows people and teams with avatars, handles, access labels, and keyboard focus, then inserts a mention chip for Priya Rao.
  • A broad @channel mention shows audience size, muted-thread limits, and a confirmation warning before the message is sent.
  • A user mentions @Dana in a private incident note, sees that Dana lacks access, chooses Invite and mention, and the resulting notification opens the exact note.
  • A user types @platform-oncall, sees the team size and notification policy, confirms the broad recipient, and the team mention remains searchable and preference-aware.
Weak implementation

Vague, hidden, hard to recover from

  • The editor highlights every @word as a mention even when it is plain text and has no recipient identity.
  • A suggestion list shows three Alex users with identical labels and lets the sender submit without disambiguating which person will be notified.
  • A user mentions someone in a private channel, the person is not notified, and the sender receives no warning or recovery path.
  • A mention notification opens the record homepage rather than the exact comment sentence, forcing the recipient to search for why they were pulled in.
UI guidance
  • Render mentions as inline tokens or highlighted text that preserve a stable recipient identity, display name, avatar or team marker, recipient type, and selected state without breaking surrounding editable text.
  • Show mention suggestions at the caret with names, handles, avatars, teams, channels, availability or scope hints, permission warnings, and keyboard-highlight state; distinguish exact matches, ambiguous display names, unavailable recipients, and broad-audience mentions.
UX guidance
  • Use mentions when a user needs to call attention to a person, team, channel, role, or group from inside a message, comment, task, document, issue, or thread while keeping the reference embedded in the authored content.
  • Bind each selected mention to notification, permission, assignment, follow-up, or deep-link behavior so recipients know why they were mentioned and can return to the exact context where the mention appeared.
Implementation contract

What the implementation must handle

States

  • Empty composer, @ trigger, loading suggestions, no results, and filtered suggestions.
  • Highlighted suggestion, keyboard-selected suggestion, mouse or touch-selected suggestion, and inserted mention token.
  • Individual, team, channel, user group, role, bot, and broad-audience mention states where the product supports them.
  • Ambiguous display name, duplicate handle, unavailable recipient, deleted user, deactivated account, and external guest states.

Interaction

  • Typing @ opens a suggestion list scoped to the current workspace, channel, object, permission boundary, and caret location.
  • Selecting a suggestion inserts an inline token bound to a stable target ID, not just the visible display name.
  • Arrow keys move through suggestions, Enter or Tab commits the highlighted target, Escape closes suggestions without deleting typed text, and Backspace removes or edits the mention predictably.
  • Submitting content validates access, broad-audience policy, duplicate recipients, quiet-hour or paused-notification behavior, and notification preferences before delivery.

Accessibility

  • Expose the suggestion list as a labelled popup tied to the editor and announce the number of available mention targets.
  • Name each suggestion with display name, handle, target type, access state, and warning state rather than relying only on avatar or color.
  • Keep the inline mention token readable as text while preserving target identity for assistive technology.
  • Announce inserted, removed, unavailable, duplicate, broad-audience, and notification-suppressed mention states.

Review

  • What stable target ID is bound to each visible mention token?
  • Can the sender tell whether they are mentioning a person, team, channel, role, bot, or broad audience?
  • What happens when several people match the same display name or handle?
  • Can every mentioned recipient see the underlying object or conversation?
Evidence trail

Source-backed claims behind this guidance

Slack supports @ member suggestions, multiple mentions, channel and DM notification behavior, private-channel non-delivery, ambiguous display-name selection, and mention activity views.

GitHub Docs: About issues

GitHub Docs - checked

GitHub issue guidance supports @mentioning collaborators who have access to draw attention to a comment.

Full agent/debug reference

Problem Context

  • Users are composing messages, comments, documents, tasks, issues, pull requests, notes, tickets, or thread replies and need to draw attention to specific people or groups.
  • Mentionable targets may include individuals, teams, channels, roles, user groups, on-call rotations, bots, or workspace-wide audiences with different notification and permission rules.
  • Mentions can create notifications, action items, task ownership, inbox filters, search handles, or audit events, but they remain embedded in authored content.
  • The recipient may lack access, have notifications paused, share a display name with another person, belong to a broad audience, or receive the mention through a team preference.

Selection Rules

  • Choose mentions when the interaction begins in prose or rich text and the user needs an inline reference that targets a recipient or audience.
  • Use object picker when the user is selecting owners, reviewers, approvers, assignees, or recipients as a structured field rather than writing a message.
  • Use comments when the product needs anchored conversation state; mentions can live inside comments but should not carry reply, resolve, edit, or delete behavior by themselves.
  • Use threaded discussion when the core task is following a branchable topic conversation; mentions inside replies should notify without changing the thread hierarchy.
  • Use notification center for the retained inbox where mention events are read, filtered, muted, or opened after delivery.
  • Use typeahead or combobox for the suggestion-list interaction, but add mention-specific recipient identity, access, and notification semantics.
  • Warn before broad mentions that reach a channel, team, workspace, or chat, especially when audience size, quiet hours, or admin rules make the effect large.
  • Do not send a mention silently when the target cannot see the object, private channel, document, issue, or thread; show invite, request access, remove, or send-without-notify choices according to product policy.

Required States

  • Empty composer, @ trigger, loading suggestions, no results, and filtered suggestions.
  • Highlighted suggestion, keyboard-selected suggestion, mouse or touch-selected suggestion, and inserted mention token.
  • Individual, team, channel, user group, role, bot, and broad-audience mention states where the product supports them.
  • Ambiguous display name, duplicate handle, unavailable recipient, deleted user, deactivated account, and external guest states.
  • Recipient lacks access, sender lacks permission to mention, admin-restricted broad mention, guest-restricted broad mention, and invite-before-mention states.
  • Notification sent, notification suppressed by preferences or paused status, thread-limited mention, failed notification, and retry or remove states.
  • Mention edited, mention removed, pasted mention text, copied mention, escaped plain @ text, and serialized mention ID states.
  • Direct-linked mention state where the recipient opens the exact message, comment, reply, task, or document location.

Interaction Contract

  • Typing @ opens a suggestion list scoped to the current workspace, channel, object, permission boundary, and caret location.
  • Selecting a suggestion inserts an inline token bound to a stable target ID, not just the visible display name.
  • Arrow keys move through suggestions, Enter or Tab commits the highlighted target, Escape closes suggestions without deleting typed text, and Backspace removes or edits the mention predictably.
  • Submitting content validates access, broad-audience policy, duplicate recipients, quiet-hour or paused-notification behavior, and notification preferences before delivery.
  • If a recipient cannot see the content, the sender gets a clear warning and an allowed recovery path such as invite, request access, remove mention, or send without notifying.
  • Mention notifications deep-link to the exact sentence, comment, task, reply, or document location and highlight the mention or its containing item on arrival.
  • Editing a mention updates the target identity, display text, notification rules, and audit or activity evidence according to product policy.

Implementation Checklist

  • Define mentionable target types, stable IDs, display labels, handles, avatars, membership, visibility, notification policy, broad-audience rules, and serialization format before building the editor.
  • Implement caret-aware suggestion positioning, keyboard navigation, loading and empty states, duplicate-name disambiguation, screen-reader labels, touch-safe rows, and mobile viewport behavior.
  • Validate access and notification outcomes at submit time, including private spaces, guest users, deactivated users, muted threads, paused notifications, broad mentions, and admin restrictions.
  • Design warning and recovery flows for broad mentions, unavailable recipients, missing access, duplicate mentions, failed notification delivery, and mention edits.
  • Ensure copied, pasted, edited, deleted, and rendered mentions preserve or intentionally drop target identity with visible feedback.
  • Test notification deep links, inbox filtering, search, action-item creation, assignment side effects, audit evidence, localization of display names, and ambiguous names.

Common Generated-UI Mistakes

  • Parsing @words after submit without requiring the sender to choose a real recipient.
  • Treating a mention suggestion list as a generic people picker and ignoring caret position, inline serialization, and notification side effects.
  • Allowing broad mentions with no audience size, policy, quiet-hours, or confirmation warning.
  • Mentioning people who cannot access the object and giving neither sender nor recipient a recoverable path.
  • Using mentions as the only assignment mechanism without creating task ownership, due state, or completion behavior.
  • Letting ambiguous display names, renamed users, deactivated users, or external guests collapse into the same visible token.
  • Sending notification links to the top of a page rather than the exact mention context.
  • Failing to distinguish person mentions, team mentions, channel mentions, bots, roles, and plain @ text.

Critique Questions

  • What stable target ID is bound to each visible mention token?
  • Can the sender tell whether they are mentioning a person, team, channel, role, bot, or broad audience?
  • What happens when several people match the same display name or handle?
  • Can every mentioned recipient see the underlying object or conversation?
  • Does the interface warn before broad mentions and respect admin, guest, quiet-hours, and notification-preference rules?
  • Where does the recipient land when they open the mention notification?
  • Does a mention also create assignment, task, or audit state, and is that state visible outside the prose?
Accessibility
  • Expose the suggestion list as a labelled popup tied to the editor and announce the number of available mention targets.
  • Name each suggestion with display name, handle, target type, access state, and warning state rather than relying only on avatar or color.
  • Keep the inline mention token readable as text while preserving target identity for assistive technology.
  • Announce inserted, removed, unavailable, duplicate, broad-audience, and notification-suppressed mention states.
  • Provide keyboard and touch access to disambiguation, invite, remove, confirm broad mention, and send-without-notify controls.
  • When a mention notification opens, move focus to the containing message, comment, task, or document location and identify the mention context.
Keyboard Behavior
  • Typing @ opens suggestions at the caret without moving focus away from the editor.
  • Arrow keys move through suggestions, Enter or Tab inserts the highlighted mention, Escape closes suggestions and leaves typed text intact.
  • Backspace on an inserted token selects or removes the whole mention before deleting surrounding prose.
  • Tab order reaches broad-mention confirmation, access recovery, invite, remove, and send controls in a logical order.
  • After inserting a mention, focus returns to the editor immediately after the token.
  • When a notification deep link opens a mention, focus moves to the mentioned item or a heading that names the containing context.
Variants
  • Person mention
  • Team mention
  • Channel mention
  • Workspace mention
  • Role mention
  • On-call mention
  • Bot mention
  • Action-item mention
  • Guest mention
  • Broad-audience mention

Verification

Source trail checked:

Saved items