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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/mentions.md.
Leaf UIReact components
GitHub

Mentions

Insert people or references into text.

Basic usage

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 },
      ]}
    />
  );
}

Different prefixes

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' },
      ]}
    />
  );
}

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
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' },
      ]}
    />
  );
}

MentionOption

PropertyTypeDefaultDescription
valuestring—Required. Controlled value.
labelReactNode—Visible label or content.
searchLabelstring—Plain text used for searching.
disabledboolean—Disable interaction.

Mentions API

PropertyTypeDefaultDescription
size'sm' | 'md' | 'lg'—Presentation size.
status'error' | 'warning'—Configure status.
resize'none' | 'vertical' | 'both'—Configure resize.
autoSizeboolean | TextareaAutoSize—Configure auto size.
showCountboolean | ((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.
popupWidthnumber | string'trigger'Popup width: trigger matches the field, auto fits content (and may be narrower), numbers specify fixed pixels; CSS lengths are also supported
popupMaxWidthnumber | string—Optional maximum width; unset by default, still bounded by the viewport
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—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.
valuestring—Controlled value.
defaultValuestring''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, prefix: string) => void—Called when an item is selected.
optionsreadonly MentionOption[]—Required. Available options.
prefixesreadonly string[]—Text prefixes that trigger suggestions.
splitstring' 'Separator appended after inserting a reference.
loadingboolean—Show a loading state.
notFoundContentReactNode—Content when no options match.

Types and interaction

Import the props and data types when creating reusable configuration.

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.