InputsReact

Mention Input

A text field that suggests people, channels or tags after a trigger character.

Rendered by React 19.3.1

Loading React…

import { MentionInput } from '@hamur/react/mention-input'

interface Person {
  label: string
  handle: string
}

const people: Person[] = [
  { label: 'Alice Johnson', handle: 'alice' },
  { label: 'Ben Okafor', handle: 'ben' },
  { label: 'Chloé Martin', handle: 'chloe' },
  { label: 'Dmitri Ivanov', handle: 'dmitri' },
  { label: 'Emma Larsen', handle: 'emma' },
  { label: 'Farah Haddad', handle: 'farah' },
]

const insertText = (person: Person, trigger: string) => `${trigger}${person.handle}`

export default function MentionInputExample() {
  return (
    <MentionInput.Root items={people} itemToInsertText={insertText}>
      <label className="field">
        <span className="select-label">Comment</span>
        <MentionInput.Input
          className="textarea mention-input"
          placeholder="Type @ to mention a teammate"
        />
      </label>
      <MentionInput.Portal>
        <MentionInput.Positioner
          className="select-positioner"
          sideOffset={6}
        >
          <MentionInput.Popup className="select-popup mention-input-popup">
            <MentionInput.Empty className="combobox-empty">
              No teammates found.
            </MentionInput.Empty>
            <MentionInput.List aria-label="Teammates" className="select-list">
              <MentionInput.Collection>
                {(person: Person) => (
                  <MentionInput.Item
                    key={person.handle}
                    value={person}
                    className="select-item mention-input-item"
                  >
                    {person.label}
                    <span className="mention-input-handle">@{person.handle}</span>
                  </MentionInput.Item>
                )}
              </MentionInput.Collection>
            </MentionInput.List>
          </MentionInput.Popup>
        </MentionInput.Positioner>
      </MentionInput.Portal>
    </MentionInput.Root>
  )
}

Not measured yetTests passing in React

Not measured yetSize

Not measured yetMemory

Not measured yetSpeed

[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<MentionInput.Root>
  <MentionInput.Input />
  <MentionInput.Portal>
    <MentionInput.Positioner>
      <MentionInput.Popup>
        <MentionInput.Empty />
        <MentionInput.List>
          <MentionInput.Collection>
            <MentionInput.Item />
          </MentionInput.Collection>
        </MentionInput.List>
      </MentionInput.Popup>
    </MentionInput.Positioner>
  </MentionInput.Portal>
</MentionInput.Root>

// Not in this example: MentionInput.Arrow, MentionInput.Group, MentionInput.GroupLabel, MentionInput.Row, MentionInput.Separator

Examples

Triggers

A message box with trigger @ and #: onQueryChange swaps the items between people and channels, and names the List for each.

MentionInputTriggers.tsx

import * as React from 'react'
import { MentionInput, type MentionInputQuery } from '@hamur/react/mention-input'

const people = ['Alice', 'Ben', 'Chloé', 'Dmitri', 'Emma', 'Farah']
const channels = ['general', 'design', 'engineering', 'releases', 'random']
const triggers = ['@', '#']

export default function MentionInputTriggersExample() {
  const [trigger, setTrigger] = React.useState('@')
  const onQueryChange = (query: MentionInputQuery | null) => {
    if (query) setTrigger(query.trigger)
  }
  return (
    <MentionInput.Root
      trigger={triggers}
      items={trigger === '#' ? channels : people}
      onQueryChang={onQueryChange}
    >
      <label className="field">
        <span className="select-label">Message</span>
        <MentionInput.Input
          className="textarea mention-input"
          placeholder="Type @ for people, # for channels"
        />
      </label>
      <MentionInput.Portal>
        <MentionInput.Positioner
          className="select-positioner"
          sideOffset={6}
        >
          <MentionInput.Popup className="select-popup mention-input-popup">
            <MentionInput.Empty className="combobox-empty">
              No matches.
            </MentionInput.Empty>
            <MentionInput.List
              aria-label={trigger === '#' ? 'Channels' : 'People'}
              className="select-list"
            >
              <MentionInput.Collection>
                {(item: string) => (
                  <MentionInput.Item
                    key={item}
                    value={item}
                    className="select-item plain"
                  >
                    {trigger === '#' ? `#${item}` : item}
                  </MentionInput.Item>
                )}
              </MentionInput.Collection>
            </MentionInput.List>
          </MentionInput.Popup>
        </MentionInput.Positioner>
      </MentionInput.Portal>
    </MentionInput.Root>
  )
}

API reference

60 props across 14 parts, in React syntax. className, style, render are listed once, under Shared props.

Arrow`MentionInput.Arrow`

Arrow data attributes
Data attribute	Description
`data-open`	Present when the popup is open.
`data-closed`	Present when the popup is closed.
`data-side`	Indicates which side the popup is positioned relative to the trigger.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-uncentered`	Present when the arrow is uncentered.

Collection`MentionInput.Collection`

Renders filtered list items. If rendering a flat list, pass a function child to the List component instead, which implicitly wraps it. Doesn’t render its own element.

Collection props
Prop	Type	Default
`children`required	`(item: any, index: number) => React.ReactNode`	`—`

Empty`MentionInput.Empty`

Group`MentionInput.Group`

Group props
Prop	Type	Default
`items`Items to be rendered within this group.	`readonly any[]`	`—`

GroupLabel`MentionInput.GroupLabel`

Input`MentionInput.Input`

The text field the mentions are typed into, on the Combobox store's reference props., or a single-line <input> with render={<input />}. Renders a <textarea>.

Input props
Prop	Type	Default
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`

Item`MentionInput.Item`

Item props
Prop	Type	Default
`children`	`React.ReactNode`	`—`
`onClick`An optional click handler for the item when selected.	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	`—`
`index`The index of the item in the list.	`number`	`—`
`value`A unique value that identifies this item.	`any`	`null`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`

List`MentionInput.List`

List props
Prop	Type	Default
`children`	`React.ReactNode \| ((item: any, index: number) => React.ReactNode)`	`—`

Popup`MentionInput.Popup`

Popup props
Prop	Type	Default
`initialFocus`Determines the element to focus when the popup is opened.	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`	`—`
`finalFocus`Determines the element to focus when the popup is closed.	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`	`—`

Popup data attributes
Data attribute	Description
`data-open`	Present when the popup is open.
`data-closed`	Present when the popup is closed.
`data-starting-style`	Present when the popup begins animating in.
`data-ending-style`	Present when the popup is animating out.
`data-side`	Indicates which side the popup is positioned relative to the trigger.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-empty`	Present when the items list is empty.

Portal`MentionInput.Portal`

Portal props
Prop	Type	Default
`keepMounted`Whether to keep the portal mounted in the DOM while the popup is hidden.	`boolean`	`false`
`container`A parent element to render the portal element into.	`HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`	`—`

Positioner`MentionInput.Positioner`

Positions the popup against the trigger character in the field. Renders a <div>.

Positioner props
Prop	Type	Default
`anchor`An element to position the popup against.	`Element \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null`	`—`
`positionMethod`Determines which CSS `position` property to use.	`"absolute" \| "fixed"`	`'absolute'`
`side`Which side of the anchor element to align the popup against.	`Side`	`'bottom'`
`sideOffset`Distance between the anchor and the popup in pixels.	`number \| OffsetFunction`	`0`
`alignOffset`Additional offset along the alignment axis in pixels.	`number \| OffsetFunction`	`0`
`collisionBoundary`An element or a rectangle that delimits the area that the popup is confined to.	`Boundary`	`'clipping-ancestors'`
`collisionPadding`Additional space to maintain from the edge of the collision boundary.	`Padding`	`5`
`sticky`Whether to maintain the popup in the viewport after	`boolean`	`false`
`arrowPadding`Minimum distance to maintain between the arrow and the edges of the popup.	`number`	`5`
`disableAnchorTracking`Whether to disable the popup from tracking any layout shift of its positioning anchor.	`boolean`	`false`
`collisionAvoidance`Determines how to handle collisions when positioning the popup.	`CollisionAvoidance`	`—`
`align`How to align the popup relative to the specified side.	`Align`	`'start'`

Positioner data attributes
Data attribute	Description
`data-open`	Present when the popup is open.
`data-closed`	Present when the popup is closed.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-side`	Indicates which side the popup is positioned relative to the trigger.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-empty`	Present when the items list is empty.

Positioner CSS variables
CSS variable	Description
`--available-width`	The available width between the trigger and the edge of the viewport.
`--available-height`	The available height between the trigger and the edge of the viewport.
`--anchor-width`	The anchor's width.
`--anchor-height`	The anchor's height.
`--transform-origin`	The coordinates that this element is anchored to. Used for animations and transitions.

Root`MentionInput.Root`

Groups all parts of the mention input: a text field that suggests items after a trigger character.; the status region is rendered after its children. Doesn’t render its own element.

Root props
Prop	Type	Default
`children`	`React.ReactNode`	`—`
`value`The text of the field.	`string`	`—`
`defaultValue`The text of the field when it's initially rendered.	`string`	`—`
`onValueChange`Event handler called when the text of the field changes.	`((value: string, eventDetails: MentionInputRootChangeEventDetails) => void)`	`—`
`trigger`The characters that start a query: one character, or a list of characters or of	`string \| readonly (string \| MentionInputTrigger)[]`	`'@'`
`insertSuffix`The text inserted after an item's text, left out when whitespace already follows the caret.	`string`	`' '`
`itemToInsertText`Converts an item to the text that replaces the trigger and the query.	`((itemValue: ItemValue, trigger: string) => string)`	`—`
`itemToStringValue`Converts an item to the string it is filtered and inserted by.	`((itemValue: ItemValue) => string)`	`—`
`items`The items to be displayed in the list.	`readonly ItemValue[] \| readonly Group<ItemValue>[]`	`—`
`filteredItems`Filtered items to display in the list, used instead of filtering `items` by the query.	`readonly ItemValue[] \| readonly Group<ItemValue>[]`	`—`
`filter`Filter function used to match items against the query.	`((item: ItemValue, query: string, itemToString?: ((item: ItemValue) => string) \| undefined) => boolean) \| null`	`—`
`limit`The maximum number of items to display in the list.	`number`	`-1`
`locale`The locale used by the default filter.	`Intl.LocalesArgument`	`—`
`onQueryChange`Event handler called when the query the caret is in changes, or ends (`null`).	`((query: MentionInputQuery \| null, eventDetails: MentionInputRootChangeEventDetails) => void)`	`—`
`onItemInsert`Event handler called before an item is inserted.	`((itemValue: ItemValue, eventDetails: MentionInputInsertEventDetails) => void)`	`—`
`onOpenChange`Event handler called when the popup is opened or closed.	`((open: boolean, eventDetails: MentionInputRootOpenChangeEventDetails) => void)`	`—`
`onOpenChangeComplete`Event handler called after any animations complete when the popup is opened or closed.	`((open: boolean) => void)`	`—`
`onItemHighlighted`Callback fired when an item is highlighted or unhighlighted.	`((highlightedValue: ItemValue \| undefined, eventDetails: AriaCombobox.HighlightEventDetails) => void)`	`—`
`autoHighlight`Whether the first enabled item is highlighted when the popup opens and when the list	`boolean`	`true`
`keepHighlight`Whether the highlighted item should be preserved when the pointer leaves the list.	`boolean`	`false`
`highlightItemOnHover`Whether moving the pointer over items should highlight them.	`boolean`	`true`
`loopFocus`Whether to loop keyboard focus back to the first item when the end of the list is reached.	`boolean`	`true`
`grid`Whether the items are arranged in a grid.	`boolean`	`false`
`virtualized`Whether the items are being externally virtualized.	`boolean`	`false`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`readOnly`Whether the user should be unable to change the text.	`boolean`	`false`
`required`Whether the field must be filled before the owning form is submitted.	`boolean`	`false`
`name`Identifies the field when a form is submitted.	`string`	`—`
`form`Identifies the form that owns the field.	`string`	`—`
`id`The id of the field.	`string`	`—`
`inputRef`A ref to the field element.	`React.Ref<HTMLInputElement \| HTMLTextAreaElement>`	`—`
`labels`The texts of the status region, merged over the English defaults.	`Partial<MentionInputLabels>`	`—`
`actionsRef`A ref to imperative actions.	`React.RefObject<MentionInputRootActions \| null>`	`—`

Row`MentionInput.Row`

Separator`MentionInput.Separator`

Separator props
Prop	Type	Default
`orientation`The orientation of the separator.	`Orientation`	`'horizontal'`

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State & State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State & State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State & State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`ArrowDownArrowUp`	While open, moves the highlight, skipping disabled items and looping	Input
`Enter`	Puts the highlighted item in place of the query	Input
`Enter`	With nothing highlighted, is the field's: a line break, and the popup closes	Input
`Escape`	Closes the popup; typing on in the same query does not open it again	Input
`Tab`	Never puts an item in; focus moves on and the popup closes	Input
	Is the field's: the arrows move the caret, `Enter` adds a line	Input

Accessibility

What the parts set
Part	Sets	So that
Input	on a `<textarea>`, no role (it stays a textbox), `aria-autocomplete="list"` and `aria-haspopup="listbox"`	a multi-line field is still read and edited as one, and says it has suggestions
Input	on an `<input>`, `role="combobox"` with `aria-expanded`	a single-line field is read as an editable combobox that says whether the popup is shown
Input	`aria-controls` to the List while the popup is open, `aria-activedescendant` to the highlighted item	the highlight is read while focus stays in the field
List	`role="listbox"`, named by the app (`aria-label`)	the suggestions are announced as a list with a name, such as "Teammates"
Item	`role="option"`, no `aria-selected`	each suggestion is read as an option; nothing is remembered as a selection
Root	a polite status region after its children: "5 suggestions", "No suggestions", then "@alice inserted"	the count and the insertion are announced without moving focus; `labels` translates them

Focus order

Focus stays in the Input the whole time; the arrows move a highlight in the list, not focus.
Nothing in the popup is a Tab stop, and a press on an item keeps focus and the caret in the field.
Tab moves on to the next element; the blur closes the popup.

Installation

Anatomy

Examples

Triggers

API reference

ArrowMentionInput.Arrow

CollectionMentionInput.Collection

EmptyMentionInput.Empty

GroupMentionInput.Group

GroupLabelMentionInput.GroupLabel

InputMentionInput.Input

ItemMentionInput.Item

ListMentionInput.List

PopupMentionInput.Popup

PortalMentionInput.Portal

PositionerMentionInput.Positioner

RootMentionInput.Root

RowMentionInput.Row

SeparatorMentionInput.Separator