Playground

Mentions

A textarea that suggests people when you type @.

  • Built on native elements
  • The textarea keeps its native textbox role (ARIA does not allow combobox on a textarea) and adds aria-haspopup="listbox", aria-autocomplete="list", aria-controls while the list is open and aria-activedescendant for the highlighted option; the list is a listbox of options.
  • ArrowDown/ArrowUp move the highlight, Enter or Tab insert the mention, Escape closes the list without inserting; focus never leaves the textarea.
  • A polite status region announces how many suggestions there are, and when they are loading or empty.
  • Styles in one file: 03-form-fields.css

Import

import '@monoline/css';
import {Mentions} from '@monoline/react';

Not installed yet? Pick a route.

Copies the source and its styles into your project.

npx monoline add mentions

Usage

import {Field, Mentions, type MentionOption} from '@monoline/react';

const people: MentionOption[] = [
  {value: 'ada', label: 'Ada Lovelace'},
  {value: 'grace', label: 'Grace Hopper'},
  {value: 'alan', label: 'Alan Turing'},
  {value: 'linus', label: 'Linus Torvalds', disabled: true},
];

<div style={{maxWidth: '360px', minHeight: '220px'}}>
  <Field label="Comment">
    <Mentions options={people} rows={3} />
  </Field>
</div>

Examples

Static options

Type @ at the start of a word.

Loaded as you type

Props

MentionsProps

PropTypeDefaultDescription
valuestring–The text when controlled. Pair with `onValueChange`.
defaultValuestring''The initial text when uncontrolled. Default empty.
onValueChange((value: string) => void)–Called with the full text after every edit and after a mention is inserted.
optionsMentionOption[][]The choices, filtered by what is typed after the trigger. Use `onSearch` instead to load them.
onSearch((query: string, trigger: string) => MentionOption[] | Promise<MentionOption[]>)–Loads choices for the typed query, for example from a server. Return the options or a promise of them. Late answers for an older query are ignored. Replaces `options` filtering when given.
triggersstring[]['@']Characters that open the list when typed at the start of a word. Default `["@"]`.
onMentionSelect((option: MentionOption, trigger: string) => void)–Called with the option and the trigger when the user inserts a mention.
loadingTextstring'Loading'Text shown while `onSearch` is loading. Default "Loading".
emptyTextstring'No matches'Text shown when nothing matches. Default "No matches".
invalidboolean–Marks the field as having an error: sets `aria-invalid` and shows the error border.

Data Attributes

State is exposed through attributes. Style it with these selectors, not with class toggles.

AttributeStylesheet
[aria-checked="true"]03-form-fields.css
[aria-invalid="true"]03-form-fields.css
[aria-pressed="true"]03-form-fields.css
[aria-disabled="true"]mentions.css
[data-active]mentions.css

CSS classes

ClassStylesheet
.field03-form-fields.css
.field-hint03-form-fields.css
.input03-form-fields.css
.input-bare03-form-fields.css
.input-end03-form-fields.css
.input-lg03-form-fields.css
.input-sm03-form-fields.css
.input-wrap03-form-fields.css
.muted03-form-fields.css
.seg03-form-fields.css
.seg-opt03-form-fields.css
.select03-form-fields.css
.setting03-form-fields.css
.switch03-form-fields.css
.textarea03-form-fields.css
.mentionsmentions.css
.mentions-listmentions.css
.mentions-notementions.css
.mentions-optionmentions.css

Customization

Style it with the kit's tokens in your own CSS, loaded after @monoline/css. Prefer the attributes above over extra classes. See Theming for every token.

app.css
.field {
  border-color: var(--accent);
}
.field[aria-checked="true"] {
  background: var(--wash);
}

Accessibility

  • The textarea keeps its native textbox role (ARIA does not allow combobox on a textarea) and adds aria-haspopup="listbox", aria-autocomplete="list", aria-controls while the list is open and aria-activedescendant for the highlighted option; the list is a listbox of options.
  • ArrowDown/ArrowUp move the highlight, Enter or Tab insert the mention, Escape closes the list without inserting; focus never leaves the textarea.
  • A polite status region announces how many suggestions there are, and when they are loading or empty.
  • Async loading ignores answers for outdated queries so the list never shows stale results.

Keyboard

KeysAction
ArrowDown / ArrowUpMove the highlight
Enter / TabInsert the mention
EscapeCloses the list without inserting