Mention

Pro

An @mention in a message that opens a person card. Hover to peek, click or tap to pin it open. The same card works on a chip in the text, an author name or an avatar.

The launch post is ready. can you check the hero image before we ship?

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add mention

Usage#

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Anatomy#

import {  Mention,  MentionCard,  MentionCardDescription,  MentionCardFooter,  MentionCardHeader,  MentionCardHeading,  MentionCardMeta,  MentionCardMetaItem,  MentionCardTitle,  MentionTrigger,} from "@/components/ui/mention"<Mention>  <MentionTrigger />  <MentionCard>    <MentionCardHeader>      <MentionCardHeading>        <MentionCardTitle />        <MentionCardDescription />      </MentionCardHeading>    </MentionCardHeader>    <MentionCardMeta>      <MentionCardMetaItem />    </MentionCardMeta>    <MentionCardFooter />  </MentionCard></Mention>

Chip in text#

The default trigger is a faint ink chip that sits on the line like the words around it and wraps with them. It darkens on hover and stays lit while its card is open.

Thanks , the renewal call went well. Looping in for the export fix.

Author name#

Set variant="plain" for the name above a message. It keeps the weight of a name and only dims on hover, so the header stays calm.

Pushed the fix for the export timeout.

Avatar trigger#

With asChild any element opens the card, such as an avatar. Wrap it in a button with a label so it can take focus. In a thread where the name beside it is already a trigger, give the avatar tabIndex={-1} and aria-hidden so the card is reached once.

Rendering a message#

Messages arrive as plain text. splitMentions cuts one into strings and mentions of the people you pass, and you render a Mention for each person it finds.

Pushed the fix for the export timeout. can you let the finance team know?

Done. They want a walkthrough next week, and are you free on Tuesday?

With the composer#

Mention shows a person once the message is sent. For the @ autocomplete while typing, wrap the Prompt Input in PromptInputMentions and give each row the same name splitMentions matches. Send a message and its mentions open cards.

Draft is in the shared folder, has the final copy.

Click to pin, and touch#

Hover is only a peek: the card opens after 400ms and closes when the pointer leaves. A click or a tap on the trigger pins it, so it stays while you read or reach a button. Click the trigger again, press Escape or click outside to close it. On touch a tap pins it and a long press opens it too.

Ask about the launch date.

Card closed

API reference#

Mention

The root, a Hover Card that can also be pinned. Hover opens it after a short delay, a click or tap on the trigger pins it open, and Escape or a click outside closes it. On touch a long press opens it too.

PropTypeDefaultDescription
openboolean-Controlled open state.
defaultOpenbooleanfalseInitial open state when uncontrolled.
onOpenChange(open: boolean) => void-Called when the card opens or closes. A pinned card ignores the pointer leaving.
openDelaynumber400Milliseconds the pointer rests on the trigger before the card opens.
closeDelaynumber150Milliseconds before the card closes once the pointer leaves, so it can travel into the card.
childrenReactNode-A MentionTrigger and a MentionCard.

MentionTrigger

What opens the card: a button by default, so it takes focus and a click pins the card. Accepts className, merged last, like every part below.

PropTypeDefaultDescription
variant"chip" | "plain""chip"chip is a faint ink chip for an @Name inside text. plain is bare text that dims on hover, for an author name.
asChildbooleanfalseRenders your element instead, such as an avatar. The variant styles are not applied.
onClick(event: MouseEvent) => void-Runs before the pin. Call event.preventDefault() to stop the click from pinning.
Data attributeDescription
data-stateopen or closed, from the Hover Card trigger.
data-slotmention.

MentionCard

The card, a HoverCardContent 288px wide. Takes every Hover Card content prop. A click on its own trigger does not count as outside, so it toggles the pin instead of closing and reopening.

PropTypeDefaultDescription
align"start" | "center" | "end""start"Alignment against the trigger. start lines the card up with the start of the name.
side"top" | "right" | "bottom" | "left""bottom"Preferred side; it flips when there is no room.
sideOffsetnumber8Gap between the trigger and the card, in pixels.
Data attributeDescription
data-stateopen or closed.
data-slotmention-card.

MentionCardHeader

The top row: an avatar beside the heading. A div.

MentionCardHeading

Stacks the title over the description and truncates both. A div.

MentionCardTitle

The person's name, in semibold. A p.

MentionCardDescription

One muted line under the name, such as a role. A p.

MentionCardMeta

A list of facts under the header: local time, place, team. A ul.

MentionCardMetaItem

One fact, an li with an icon and a line of text that truncates.

PropTypeDefaultDescription
iconReactNode-A 16px glyph before the text, hidden from screen readers.

MentionCardFooter

A row of actions at the bottom; each child takes an even share of the width. A div.

splitMentions

A helper that splits a message into plain strings and mentions, so you can render a Mention for each person. Names match whole words, ignore case and prefer the longest name.

PropTypeDefaultDescription
text*string-The message to split.
people*{ id: string; name: string }[]-Who can be mentioned. name is what follows the trigger, such as a first name.
triggerstring"@"The character that starts a mention.
returns(string | { id: string; text: string })[]-The segments in order. A mention keeps its trigger in text, as in @Priya.

FAQ#

Hover Card previews where a link goes and never takes a click. Mention is for a person: the trigger is a button, a click pins the card open, and the card can hold actions like Message or Call.