Dice UI
Components

Mention

A component that allows to mention items in a list by a trigger character.

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.

"use client";
 
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.

PropTypeDefault
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 AttributeValue
[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.

PropTypeDefault
asChild
boolean
-

Input

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

PropTypeDefault
asChild
boolean
-

Portal

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

PropTypeDefault
container
HTMLElement | DocumentFragment
document.body

Content

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

PropTypeDefault
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 AttributeValue
[data-state]"open" | "closed"
[data-side]"top" | "right" | "bottom" | "left"
[data-align]"start" | "center" | "end"
CSS VariableDescriptionDefault
--dice-transform-originTransform origin for cursor positioning.
--dice-available-widthAvailable width in the viewport for the popover element.
--dice-available-heightAvailable height in the viewport for the popover element.

Item

An interactive option in the mention list.

PropTypeDefault
label
string
-
asChild
boolean
-
value
string
-
disabled
boolean
-
Data AttributeValue
[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

KeyDescription
EnterWhen open, selects the highlighted mention option.
ArrowUpWhen open, highlights the previous mention option.
ArrowDownWhen open, highlights the next mention option.
HomeWhen open, highlights the first mention option.
EndWhen open, highlights the last mention option.
EscapeCloses the mention popover and returns focus to the input.

On this page