Component reference
Mentions
Mention teammates while writing a project update.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Width adapts to the available space
"use client";
import { useState } from "react";
import { Mentions, type PimoluMentionsOption, Avatar, Button } from "@pimolu/react";
const teammates: PimoluMentionsOption[] = [
{
id: "alice",
label: "Alice Martin",
description: "Product designer · Paris",
avatar: <Avatar name="Alice Martin" size="xs" />,
},
{
id: "bob",
label: "Bob Chen",
description: "Front-end engineer · Lyon",
avatar: <Avatar name="Bob Chen" size="xs" />,
},
{
id: "carol",
label: "Carol Diallo",
description: "Engineering manager · Dakar",
avatar: <Avatar name="Carol Diallo" size="xs" />,
},
{
id: "dana",
label: "Dana Novak",
description: "Data analyst · Prague",
avatar: <Avatar name="Dana Novak" size="xs" />,
},
];
function ProjectUpdateExample() {
const [value, setValue] = useState("Hi @Alice Martin, the new tokens are ready for review. ");
const [lastMention, setLastMention] = useState("");
return (
<div className="grid gap-5 min-w-0">
<Mentions
label="Project update"
placeholder="Write an update and mention a teammate…"
options={teammates}
value={value}
onValueChange={setValue}
onSelect={(option) => setLastMention(option.label)}
rows={4}
fullWidth
/>
<div className="flex flex-wrap items-center gap-3 min-w-0 justify-between">
<span className="text-sm text-muted leading-relaxed">
{
lastMention
? `Last mention: ${lastMention}`
: "No mention selected yet."
}
</span>
<Button size="sm" disabled={value.trim() === ""}>Post update</Button>
</div>
</div>
);
}
export function DemoExample() {
return (<ProjectUpdateExample />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Custom trigger
The trigger is configurable and allowCreate offers the current query as a new mention.
States and suggestions
Helper text, a limited number of suggestions, several mentions in one text, and a disabled composer.
Examples
The same field used in two real communication flows.
Usage
Use stable mention ids and validate referenced users on the server.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluMentionsOption
Type source| Name | Type | Default | Description |
|---|---|---|---|
idRequired | string | — | Stable identifier reported by `onSelect`. |
labelRequired | string | — | Text inserted after the trigger. |
description | string | undefined | — | Optional secondary line in the suggestion list. |
avatar | ReactNode | — | Optional avatar rendered before the label. |
idRequiredstringNo default extracted.
Stable identifier reported by `onSelect`.
labelRequiredstringNo default extracted.
Text inserted after the trigger.
descriptionstring | undefinedNo default extracted.
Optional secondary line in the suggestion list.
avatarReactNodeNo default extracted.
Optional avatar rendered before the label.
PimoluMentionsProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
id | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
name | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
optionsRequired | readonly PimoluMentionsOption[] | — | Public Pimolu prop; see the source declaration for details. |
value | string | undefined | — | Controlled text value. |
defaultValue | string | undefined | "" | Initial text when uncontrolled. |
onValueChange | ((value: string) => void) | undefined | — | Public Pimolu prop; see the source declaration for details. |
onSelect | ((option: PimoluMentionsOption) => void) | undefined | — | Called when a suggestion is chosen or created. |
trigger | string | undefined | "@" | Character that opens the suggestion list. Defaults to "@". |
maxSuggestions | number | undefined | 6 | Maximum number of suggestions rendered at once. |
placeholder | string | undefined | "Type a message…" | Public Pimolu prop; see the source declaration for details. |
label | string | undefined | — | Visible label associated with the control. |
helperText | string | undefined | — | Supporting text rendered below the field. |
disabled | boolean | undefined | false | Public Pimolu prop; see the source declaration for details. |
allowCreate | boolean | undefined | false | Offer the current query as a new mention when nothing matches. |
rows | number | undefined | 3 | Public Pimolu prop; see the source declaration for details. |
maxLength | number | undefined | — | Public Pimolu prop; see the source declaration for details. |
required | boolean | undefined | false | Public Pimolu prop; see the source declaration for details. |
fullWidth | boolean | undefined | false | Use the available width of the parent. |
className | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
textareaClassName | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
style | CSSProperties | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-label | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-labelledby | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-describedby | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
idstring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
namestring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
optionsRequiredreadonly PimoluMentionsOption[]No default extracted.
Public Pimolu prop; see the source declaration for details.
valuestring | undefinedNo default extracted.
Controlled text value.
defaultValuestring | undefinedDefault: ""
Initial text when uncontrolled.
onValueChange((value: string) => void) | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onSelect((option: PimoluMentionsOption) => void) | undefinedNo default extracted.
Called when a suggestion is chosen or created.
triggerstring | undefinedDefault: "@"
Character that opens the suggestion list. Defaults to "@".
maxSuggestionsnumber | undefinedDefault: 6
Maximum number of suggestions rendered at once.
placeholderstring | undefinedDefault: "Type a message…"
Public Pimolu prop; see the source declaration for details.
labelstring | undefinedNo default extracted.
Visible label associated with the control.
helperTextstring | undefinedNo default extracted.
Supporting text rendered below the field.
disabledboolean | undefinedDefault: false
Public Pimolu prop; see the source declaration for details.
allowCreateboolean | undefinedDefault: false
Offer the current query as a new mention when nothing matches.
rowsnumber | undefinedDefault: 3
Public Pimolu prop; see the source declaration for details.
maxLengthnumber | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
requiredboolean | undefinedDefault: false
Public Pimolu prop; see the source declaration for details.
fullWidthboolean | undefinedDefault: false
Use the available width of the parent.
classNamestring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
textareaClassNamestring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
styleCSSProperties | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-labelstring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-labelledbystring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-describedbystring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
Accessibility
- Name the editor and verify suggestion navigation, Escape and text editing without a pointer.