> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/mentions.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Mentions

Insert people or references into text.

## Basic usage


basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/mentions/basic.tsx"
import { Mentions } from '@ifhover/leaf-ui';

export function MentionsBasic() {
  return (
    <Mentions
      aria-label={'Comment'}
      placeholder={'Type @ to mention a teammate'}
      options={[
        { value: 'ada', label: 'Ada' },
        { value: 'lin', label: 'Lin' },
        { value: 'morgan', label: 'Morgan', disabled: true },
      ]}
    />
  );
}
```

Expand code

## Different prefixes


basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/mentions/basic.tsx"
import { Mentions } from '@ifhover/leaf-ui';

export function MentionsPrefixes() {
  return (
    <Mentions
      prefixes={['@', '#']}
      aria-label={'Project note'}
      placeholder={'Use @ or # to insert a reference'}
      options={[
        { value: 'design', label: 'Design' },
        { value: 'engineering', label: 'Engineering' },
      ]}
    />
  );
}
```

Expand code

## Popup width

The popup matches the field width by default (`popupWidth="trigger"`). Set `popupWidth="auto"` to fit the content, which may be narrower than the field, or `popupWidth={300}` for a fixed 300px width; CSS lengths are also supported. `popupMaxWidth` is unset by default. The example below fits the content with an explicit maximum width. Viewport edge avoidance still applies.


popup.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/mentions/popup.tsx"
import { Mentions } from '@ifhover/leaf-ui';

export function MentionsPopup() {
  return (
    <Mentions
      aria-label={'Comment with content-sized suggestions'}
      placeholder={'Type @ to see suggestions'}
      popupWidth="auto"
      popupMaxWidth={280}
      options={[
        { value: 'design', label: 'Design team' },
        { value: 'engineering', label: 'Engineering team' },
      ]}
    />
  );
}
```

Expand code

## MentionOption

| Property      | Type        | Default | Description                    |
| ------------- | ----------- | ------- | ------------------------------ |
| `value`       | `string`    | —       | Required. Controlled value.    |
| `label`       | `ReactNode` | —       | Visible label or content.      |
| `searchLabel` | `string`    | —       | Plain text used for searching. |
| `disabled`    | `boolean`   | —       | Disable interaction.           |

## Mentions API

| Property            | Type                                                                                                                                                                 | Default     | Description                                                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | —           | Presentation size.                                                                                                                            |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —           | Configure status.                                                                                                                             |
| `resize`            | `'none' \| 'vertical' \| 'both'`                                                                                                                                     | —           | Configure resize.                                                                                                                             |
| `autoSize`          | `boolean \| `[`TextareaAutoSize`](https://ifhover.github.io/leaf-ui/en/components/textarea.md#textareaautosize-api)                                                  | —           | Configure auto size.                                                                                                                          |
| `showCount`         | `boolean \| ((value: string, maxLength?: number) => ReactNode)`                                                                                                      | —           | Configure show count.                                                                                                                         |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —           | Placement relative to the trigger.                                                                                                            |
| `popupWidth`        | `number \| string`                                                                                                                                                   | `'trigger'` | Popup width: trigger matches the field, auto fits content (and may be narrower), numbers specify fixed pixels; CSS lengths are also supported |
| `popupMaxWidth`     | `number \| string`                                                                                                                                                   | —           | Optional maximum width; unset by default, still bounded by the viewport                                                                       |
| `popupClassName`    | `string`                                                                                                                                                             | —           | Custom class for the popup.                                                                                                                   |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —           | Custom popup styles.                                                                                                                          |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —           | Wrap or extend popup content; retain the supplied content to preserve interaction.                                                            |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —           | Return a popup container, including a ShadowRoot.                                                                                             |
| `value`             | `string`                                                                                                                                                             | —           | Controlled value.                                                                                                                             |
| `defaultValue`      | `string`                                                                                                                                                             | `''`        | Initial value; uncontrolled fields support native form reset.                                                                                 |
| `onChange`          | `(value: string) => void`                                                                                                                                            | —           | Called when the value changes.                                                                                                                |
| `onSearch`          | `(query: string, prefix: string) => void`                                                                                                                            | —           | Called when the search text changes.                                                                                                          |
| `onSelect`          | `(option: `[`MentionOption`](#mentionoption)`, prefix: string) => void`                                                                                              | —           | Called when an item is selected.                                                                                                              |
| `options`           | `readonly `[`MentionOption`](#mentionoption)`[]`                                                                                                                     | —           | Required. Available options.                                                                                                                  |
| `prefixes`          | `readonly string[]`                                                                                                                                                  | —           | Text prefixes that trigger suggestions.                                                                                                       |
| `split`             | `string`                                                                                                                                                             | `' '`       | Separator appended after inserting a reference.                                                                                               |
| `loading`           | `boolean`                                                                                                                                                            | —           | Show a loading state.                                                                                                                         |
| `notFoundContent`   | `ReactNode`                                                                                                                                                          | —           | Content when no options match.                                                                                                                |

## Types and interaction

Import the props and data types when creating reusable configuration.

```ts
import type { MentionOption, MentionsProps } from '@ifhover/leaf-ui';
```

Provide accessible labels for icon-only actions. Interactive controls support keyboard navigation and respect ConfigProvider themes and reduced motion.