# Mention field

A text field for comments, notes and chat where typing @ opens a short list of people, and # a list of topics, hung under the caret. The arrow keys and Enter pick, and the pick is set into the text as a small raised token that Backspace takes away as one piece. It is the kit’s text well with the combobox’s card and options: a proper ARIA combobox, with the active option named by aria-activedescendant and the count of the list spoken as it narrows. What it holds reads as plain text with each pick written @[id], so a server can store it and a page can draw it again.

Kit part · With the Kit · https://tactileui.dev/parts/mention-field

> The code and styling for this part come with the Tactile UI Kit, which is in the Founder Pass. Sign in if you have it. Sign in: https://tactileui.dev/auth/sign-in The price: https://tactileui.dev/pricing

## Anatomy

The text well and its focus ring are the textarea’s. The list is the combobox’s own card and options, with the matched letters printed heavier and the row under the arrows pressed in, and it is placed by the popover’s rules, hung from the caret rather than a key. A token is the tag input’s raised cap set in the line of text. No colour is added: the pressed row, the cap and the heavier print are the kit’s.

## Variants

- People and topics · @ and #
- People only · one list
- With picks already in it · value
- A note · multiline
- Words of your own · data-one and data-many
- Disabled

## States

- Empty
- With a pick
- List open
- No match
- Disabled

## Props and options

| Name | Kind | Description |
| - | - | - |
| ul[data-trigger] | child | A source: the character that opens it. data-label names the list, data-one and data-many are the words for one and for several, which the count is spoken in (“3 people”). |
| li[data-id] | child of a source | One thing that can be picked. The text is its name; data-hint is the small second line (a role). The id is what is stored. |
| value · text · mentions | property | value is the text with each pick written @[id] or #[id]. Setting value draws the picks as tokens; an id that is in no list stays as written. |
| sources | property | Set it when they come from a server. |
| name | attribute | The element is form-associated: name submits value. |
| placeholder · multiline · disabled | attribute | The words shown while empty. |
| input · change | event | input on every edit; change when the focus leaves and the value is not what it was. |
| mentionTrigger() · mentionRank() · mentionSays() | function | Whether the text before the caret ends in an open mention, the list narrowed by a query (names that start with it first), and the words the count is spoken in. |
| mentionParts() · parseMentions() · mentionMarkup() · mentionFieldHTML() | function | The parts of a message to value, text and mentions; a stored value back into parts; one token as markup; and the element as markup for a server or a specimen. |

## Usage notes

Type @ma in the message field: the list narrows to Mara Voss and the count is spoken. Press Enter to take Mara (the Down arrow moves to the next name), or click a name, and it becomes a token in the line. Press Backspace straight after it and the whole name goes. Type # for a topic. Press Send (or Enter) and the message joins the thread above.

## Accessibility

- The count is spoken as the list opens and as it narrows, in the source’s own words: “3 people. Up and down to move, Enter to pick.” A query with nothing in it says “No people match ‘zq’”. A pick says “Added @Mara Voss” and a removal says “Removed @Mara Voss”.
- @ or # at the start or after a space opens the list. ↑ and ↓ move, Enter picks, Esc closes and leaves what was typed (the list stays shut until the next @), and Tab leaves. Home and End move the caret and the list follows it, opening or closing as the caret enters or leaves a mention. Backspace right after a token, or Delete right before one, removes the whole token.
- A token is a raised cap in the line that reads as its words (“@Mara Voss”); it is not a control and takes no tab stop. Pasting is plain text, so no formatting or markup comes in. Dragging text in is refused.

## Related parts

- [Text area](https://tactileui.dev/parts/textarea): Longer text in a deeper recess: notes, messages, descriptions. It grows by its corner handle.
- [Combobox](https://tactileui.dev/parts/combobox): A field that filters a long list as you type. It starts as a plain select, so it posts with the form and works without a script; then the options card slides out of a slot under the well, the letters that match print heavier and the chosen option’s lamp is lit. Several choices sit in the well as tags.
- [Tag input](https://tactileui.dev/parts/tag-input): A text input that turns what you type into printed tags. Enter or a comma sets one down in the well; each tag is a key that takes itself away, and every change is spoken.
- [Composer](https://tactileui.dev/parts/composer): The prompt box. One deep recess holds the text and the keys sit on its floor: attach at one end; at the other a small LCD that counts tokens, amber near the limit and red over it, and the send key, which becomes a stop key while a reply runs. It is a real form with a labelled text area. Enter sends and Shift and Enter make a new line, and the send key is disabled while there is nothing to send. The text grows as you type, up to a height, then scrolls.