Dice UI

Mention users

Installation

npm install @diceui/mention

Installation with shadcn/ui

CLI

npx shadcn@latest add "https://diceui.com/r/mention"

Manual

Install the following dependencies:

npm install @diceui/mention

Copy and paste the following code into your project.

import * as MentionPrimitive from "@diceui/mention";
import * as React from "react";
 
import { cn } from "@/lib/utils";
 
const Mention = React.forwardRef<
  React.ElementRef<typeof MentionPrimitive.Root>,
  React.ComponentPropsWithoutRef<typeof MentionPrimitive.Root>
>(({ className, ...props }, ref) => (
  <MentionPrimitive.Root
    ref={ref}
    className={cn(
      "**:data-tag:rounded **:data-tag:bg-blue-200 **:data-tag:py-px **:data-tag:text-blue-950 dark:**:data-tag:bg-blue-800 dark:**:data-tag:text-blue-50",
      className,
    )}
    {...props}
  />
));
Mention.displayName = MentionPrimitive.Root.displayName;
 
const MentionLabel = React.forwardRef<
  React.ElementRef<typeof MentionPrimitive.Label>,
  React.ComponentPropsWithoutRef<typeof MentionPrimitive.Label>
>(({ className, ...props }, ref) => (
  <MentionPrimitive.Label
    ref={ref}
    className={cn("px-0.5 py-1.5 font-semibold text-sm", className)}
    {...props}
  />
));
MentionLabel.displayName = MentionPrimitive.Label.displayName;
 
const MentionInput = React.forwardRef<
  React.ElementRef<typeof MentionPrimitive.Input>,
  React.ComponentPropsWithoutRef<typeof MentionPrimitive.Input>
>(({ className, ...props }, ref) => (
  <MentionPrimitive.Input
    ref={ref}
    className={cn(
      "flex w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-xs placeholder:text-muted-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
      className,
    )}
    {...props}
  />
));
MentionInput.displayName = MentionPrimitive.Input.displayName;
 
const MentionContent = React.forwardRef<
  React.ElementRef<typeof MentionPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof MentionPrimitive.Content>
>(({ className, children, ...props }, ref) => (
  <MentionPrimitive.Portal>
    <MentionPrimitive.Content
      ref={ref}
      className={cn(
        "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[state=closed]:animate-out data-[state=open]:animate-in",
        className,
      )}
      {...props}
    >
      {children}
    </MentionPrimitive.Content>
  </MentionPrimitive.Portal>
));
MentionContent.displayName = MentionPrimitive.Content.displayName;
 
const MentionItem = React.forwardRef<
  React.ElementRef<typeof MentionPrimitive.Item>,
  React.ComponentPropsWithoutRef<typeof MentionPrimitive.Item>
>(({ className, children, ...props }, ref) => (
  <MentionPrimitive.Item
    ref={ref}
    className={cn(
      "relative flex w-full cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden data-disabled:pointer-events-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:opacity-50",
      className,
    )}
    {...props}
  >
    {children}
  </MentionPrimitive.Item>
));
MentionItem.displayName = MentionPrimitive.Item.displayName;
 
export { Mention, MentionContent, MentionInput, MentionItem, MentionLabel };

Layout

Import the parts, and compose them together.

import * as Mention from "@diceui/mention";
 
<Mention.Root>
  <Mention.Label />
  <Mention.Input />
  <Mention.Portal>
    <Mention.Content>
      <Mention.Item />
    </Mention.Content>
  </Mention.Portal>
</Mention.Root>

Examples

Custom Trigger

With Custom Filter

API Reference

Root

The container for all mention parts. Mention tags can be styled using the data-tag attribute within the root.

Prop	Type	Default
`defaultValue`	`string[]`	-
`value`	`string[]`	-
`onValueChange`	`(value: string[]) => void`	-
`asChild`	`boolean`	-
`open`	`boolean`	-
`defaultOpen`	`boolean`	-
`onOpenChange`	`(open: boolean) => void`	-
`inputValue`	`string`	-
`onInputValueChange`	`(value: string) => void`	-
`trigger`	`string`	-
`disabled`	`boolean`	-
`onFilter`	`(options: string[], term: string) => string[]`	-
`exactMatch`	`boolean`	`false`
`loop`	`boolean`	`false`
`modal`	`boolean`	`false`
`readonly`	`boolean`	`false`
`required`	`boolean`	`false`
`name`	`string`	-

Data Attribute	Value
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled.

Label

An accessible label that describes the mention input. Associates with the input element for screen readers.

Prop	Type	Default
`asChild`	`boolean`	-

Input

The text input field that users can type into to trigger mentions.

Prop	Type	Default
`asChild`	`boolean`	-

Portal

A portal for rendering the mention content outside of its DOM hierarchy.

Prop	Type	Default
`container`	`Element \| DocumentFragment`	`document.body`

Content

The popover container for mention items. Positions the mention popover relative to the cursor position.

Prop	Type	Default
`side`	`Side`	`"bottom"`
`sideOffset`	`number`	`4`
`align`	`Align`	`"start"`
`alignOffset`	`number`	`0`
`collisionBoundary`	`Boundary`	-
`collisionPadding`	`number \| Partial<Record<Side, number>>`	`0`
`arrowPadding`	`number`	`0`
`sticky`	`"partial" \| "always"`	`"partial"`
`strategy`	`Strategy`	`"absolute"`
`avoidCollisions`	`boolean`	`true`
`fitViewport`	`boolean`	`false`
`forceMount`	`boolean`	`false`
`hideWhenDetached`	`boolean`	`false`
`trackAnchor`	`boolean`	`true`
`asChild`	`boolean`	-
`onEscapeKeyDown`	`(event: KeyboardEvent) => void`	-
`onPointerDownOutside`	`(event: PointerDownOutsideEvent) => void`	-

Data Attribute	Value
`[data-state]`	`"open" \| "closed"`
`[data-side]`	`"top" \| "right" \| "bottom" \| "left"`
`[data-align]`	`"start" \| "center" \| "end"`

CSS Variable	Description	Default
`--dice-transform-origin`	Transform origin for cursor positioning.	—
`--dice-available-width`	Available width in the viewport for the popover element.	—
`--dice-available-height`	Available height in the viewport for the popover element.	—

Item

An interactive option in the mention list.

Prop	Type	Default
`label`	`string`	-
`asChild`	`boolean`	-
`value`	`string`	-
`disabled`	`boolean`	-

Data Attribute	Value
`[data-highlighted]`	Present when the item is highlighted.
`[data-disabled]`	Present when the item is disabled.
`[data-value]`	The value of the item.

Accessibility

Keyboard Interactions

Key	Description
`Enter`	When open, selects the highlighted mention option.
`ArrowUp`	When open, highlights the previous mention option.
`ArrowDown`	When open, highlights the next mention option.
`Home`	When open, highlights the first mention option.
`End`	When open, highlights the last mention option.
`Escape`	Closes the mention popover and returns focus to the input.

Mention

On this page