Mention Input React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Mention Input is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import MentionInput from @/components/ui/mention-input.

import { useState } from "react"
import { MentionInput, MentionText, getMentions, type MentionItem } from "@/components/ui/mention-input"

const team: MentionItem[] = [
  { id: "u-daniel", label: "Daniel Reed", avatar: "/demo/mihai-ionescu.jpg", description: "Sales manager" },
  { id: "u-sophia", label: "Sophia Lee", avatar: "/demo/ioana-dumitrescu.jpg", description: "Accounting" },
]
const tags: MentionItem[] = [
  { id: "t-follow-up", label: "follow-up" },
  { id: "t-quote", label: "quote" },
]

export function ClientNote() {
  const [note, setNote] = useState("Call @[Daniel Reed](u-daniel) tomorrow #[follow-up](t-follow-up)")
  const [saved, setSaved] = useState<string[]>([])
  return (
    <div className="flex flex-col gap-3">
      <MentionInput
        label="New note"
        value={note}
        onValueChange={setNote}
        people={team}
        tags={tags}
        placeholder="Write a note. @ for teammates, # for tags"
        onSubmit={(value) => {
          console.log("notify", getMentions(value).map((m) => m.id))
          setSaved((prev) => [value, ...prev])
          setNote("")
        }}
      />
      {saved.map((value, i) => (
        <MentionText key={i} value={value} className="text-sm" />
      ))}
    </div>
  )
}

Props

• defaultValuedefault ""
  string

  The starting markup while uncontrolled. Mentions are trigger + [label](id): @[Daniel Reed](u-daniel), #[follow-up](t-follow-up); brackets and backslashes inside are escaped with \. The playground falls back to a sample note when it is empty.

• value
  string

  The markup, to control it from outside; pair it with onValueChange. A change from outside while typing keeps the caret at the same plain-text offset.

• onValueChange
  (value: string, context: MentionChangeContext) => void

  Called with the new markup on every change, plus a context { text; mentions: MentionRef[] }: the plain text people see and the mentions with their offsets (for notifications).

• onChange
  (event: ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) => void

  The native change event of the control, untouched. Its value is the plain text, not the markup.

• people
  MentionItem[]

  Shorthand for the @ trigger: { id; label; avatar?; description?; icon?; keywords?; disabled? }. Rows show the avatar (initials without a photo) and the description under the name; spaces are allowed in the query.

• tags
  MentionItem[]

  Shorthand for the # trigger. Rows show a # tile unless an item has its own icon.

• triggers
  MentionTrigger[]

  Full control: { char; items?; onSearch?(query) => Promise<MentionItem[]>; allowCreate?; onCreate?(label); tone?; color?; title?; minChars?; maxResults? (8); allowSpaces? }. char is one symbol or punctuation character. Entries win over people / tags for the same char, field by field, so { char: "@", tone: "info" } keeps the people list. onSearch is debounced 200ms and drops stale answers.

• allowCreateTagsdefault true
  boolean

  The # list ends with “Create #query” when nothing matches exactly. The created tag (onCreate's result, by default { id: label, label }) is inserted and offered again later.

• multilinedefault true
  boolean

  A textarea that grows with the text from minRows to maxRows; false renders a single-line input for task titles, where the text scrolls sideways and the chips follow.

• minRowsdefault 3
  number

  Height of the empty textarea in rows.

• maxRowsdefault 8
  number

  The textarea grows up to this many rows, then scrolls inside; the chips scroll with the text.

• placeholderdefault "Write a note. Type @ to mention someone, # to add a tag"
  string

  Shown while the field is empty; it is the best place to teach the triggers.

• sizedefault "md"
  "sm" | "md" | "lg"

  The field sizes: text 13 / 14 / 15px (16px on phones, so iOS never zooms) and one row as tall as an input of the same size.

• variantdefault "soft"
  "soft" | "outline" | "ghost"

  soft is a filled well that works on every surface, outline a bordered box, ghost invisible until hovered (inline notes).

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape, scaled per size like the button's (md is 8 / 10 / 12px). full is a pill on one line and half a row height on a taller box.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The chip tint of every trigger without its own tone or color. Neutral is a quiet gray in both themes.

• colordefault ""
  string

  Any CSS color for the chips; replaces the tone. The tint is mixed at 14% so the text on it stays readable.

• labeldefault ""
  ReactNode

  Renders the field anatomy with a label linked to the control. Leave it empty for a bare box.

• descriptiondefault ""
  ReactNode

  Helper text under the box, linked with aria-describedby. The error takes its place while it shows.

• errordefault ""
  ReactNode

  Replaces the description, slides in and marks the box invalid.

• requireddefault false
  boolean

  The required mark after the label and required on the control.

• maxLengthdefault 0
  number

  A limit on the plain text (a chip counts as its visible text). A counter sits in the box, turns amber at 90% and red at the limit, and shakes when a mention would not fit (the insert is refused).

• suggestionsPlacementdefault "auto"
  "auto" | "caret" | "below" | "above"

  auto opens the list at the caret with a mouse and attaches it to the box edge on touch, above the box when the keyboard would cover the room below. With a mouse the list is portaled above everything, so no card or dialog body ever cuts it. On touch it renders in flow against the box, so it rides every scroll with the field while the keyboard is up; when the parents that clip it (an overflow-hidden card, a sheet or dialog body) leave it too little room, it is portaled instead. A parent that isolates without clipping needs z-dropdown so the in-flow list paints over what follows it.

• onSubmit
  (value: string, context: MentionChangeContext) => (void | Promise<unknown>)

  Runs on submitShortcut with the markup and { text, mentions }. A promise locks the field (read-only, dimmed, aria-busy) until it settles. Without it the shortcut submits the surrounding form.

• submitShortcutdefault "mod+enter"
  string

  A combo in mod+k notation, bound on the field only while it has focus. "enter" makes it chat style (a bare Enter still makes new lines on touch keyboards); "" turns it off.

• disableddefault false
  boolean

  Dims the field and blocks typing.

• readOnlydefault false
  boolean

  The text and its chips stay visible and selectable; no suggestions open.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message.

• autoFocusdefault false
  boolean

  Focuses the field on mount with the caret at the end of any starting text.

• namedefault ""
  string

  Adds a hidden input with the markup, so a native form posts the mentions, not just the text.

• labels
  Partial<MentionInputLabels>

  suggestions “Suggestions”, people “People”, tags “Tags”, create (label, trigger) => “Create “#label””, empty “No matches”, loading “Searching…”, mentioned (label) => “label mentioned”, removed (label) => “label removed”, counter (count, max) => “count of max”, limitReached “Character limit reached”. Exported as DEFAULT_MENTION_INPUT_LABELS.

• classNames
  Partial<Record<"field" | "label" | "description" | "error" | "box" | "control" | "highlighter" | "chip" | "suggestions" | "option" | "counter", string>>

  Extra classes for the parts: field, label, description and error style the field anatomy, the rest the box and the list. The highlighter and the control must keep the same font, padding and line height, so style both or neither.

• className
  string

  Extra classes for the field root (the box when there is no label, description or error).

• ref
  Ref<HTMLTextAreaElement | HTMLInputElement> (a useRef object or an (el) => void callback)

  The native control. Every other prop (id, aria-*, onKeyDown, onFocus, enterKeyHint) is spread onto it too.

Parts

FAQ

Used in

More React input components