https://github.com/alexanderdunlop/mentis
A small, fast, and flexible mention input solution for React.
https://github.com/alexanderdunlop/mentis
mentions react
Last synced: 2 months ago
JSON representation
A small, fast, and flexible mention input solution for React.
- Host: GitHub
- URL: https://github.com/alexanderdunlop/mentis
- Owner: Alexanderdunlop
- License: mit
- Created: 2025-07-14T09:32:38.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-07-21T20:32:45.000Z (3 months ago)
- Last Synced: 2025-07-21T22:27:07.832Z (3 months ago)
- Topics: mentions, react
- Language: TypeScript
- Homepage: https://mentis.alexdunlop.com/
- Size: 431 KB
- Stars: 5
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Features
- 🎯 **ContentEditable Architecture** - Modern implementation with rich text support
- 🧠 **Smart Mention Detection** - DOM-aware detection that distinguishes mentions from regular text
- ⚡ **Zero Dependencies** - Lightweight with no external dependencies
- ♿ **Fully Accessible** - Complete ARIA roles and keyboard navigation
- 🎨 **Highly Customizable** - Slot-based customization system
- 🔧 **TypeScript Support** - Full type safety out of the box
- 📱 **Flexible Triggers** - Customizable trigger characters or strings
- 🎪 **Rich Text Support** - Display mentions as styled chips
- 🚀 **Function Values** - Support for executable functions as option values
- 📋 **Advanced Paste Handling** - Intelligent mention parsing from pasted content
- 🔄 **Auto-Conversion** - Optional automatic conversion of text mentions to chips
## Quick Start
```bash
npm install mentis
```
```tsx
import { MentionInput } from "mentis";
import "mentis/dist/index.css";
function App() {
const [value, setValue] = useState("");
return (
{
setValue(mentionData.value);
}}
options={[
{ label: "Alice Johnson", value: "alice" },
{ label: "Bob Smith", value: "bob" },
{ label: "Charlie Brown", value: "charlie" },
]}
/>
);
}
```
## Examples
### Basic Usage
```tsx
import { MentionInput } from "mentis";
function BasicExample() {
return (
console.log(mentionData)}
/>
);
}
```
### Function Values
```tsx
import { MentionInput } from "mentis";
function FunctionValueExample() {
return (
console.log("Message sent!") },
{ label: "Clear Input", value: () => setValue("") },
{ label: "Alice Johnson", value: "alice" },
]}
onChange={(mentionData) => console.log(mentionData)}
/>
);
}
```
### Custom Styling with Tailwind
```tsx
import { MentionInput } from "mentis";
function StyledExample() {
return (
);
}
```
### Custom Trigger Character
```tsx
import { MentionInput } from "mentis";
function CustomTriggerExample() {
return (
);
}
```
### Auto-Convert Mentions
```tsx
import { MentionInput } from "mentis";
function AutoConvertExample() {
return (
);
}
```
## API Reference
### MentionInput Props
| Prop | Type | Default | Description |
| --------------------- | ------------------------------ | ------- | ----------------------------------------------------- |
| `options` | `MentionOption[]` | - | Array of mention options |
| `value` | `string` | `""` | Current value of the input |
| `onChange` | `(value: MentionData) => void` | - | Callback when value changes with mention data |
| `trigger` | `string` | `"@"` | Character(s) that trigger the mention dropdown |
| `keepTriggerOnSelect` | `boolean` | `true` | Whether to keep the trigger character after selection |
| `autoConvertMentions` | `boolean` | `false` | Automatically convert mentions to chips |
| `slotsProps` | `SlotProps` | - | Customization props for different parts |
### MentionOption
```tsx
type MentionOption = {
label: string; // Display text
value: string | Function; // Unique identifier or executable function
};
```
### MentionData
```tsx
type MentionData = {
value: string; // Text as displayed to user (with mention labels)
dataValue: string; // Text with mention values (actual data)
mentions: Array<{
label: string; // Display text of the mention
value: string; // Unique identifier of the mention
startIndex: number; // Start position in the text
endIndex: number; // End position in the text
}>;
};
```
### SlotProps
```tsx
type SlotProps = {
container?: React.HTMLAttributes;
contentEditable?: ContentEditableInputCustomProps;
modal?: ModalProps;
option?: OptionProps;
noOptions?: React.HTMLAttributes;
highlightedClassName?: string;
chipClassName?: string;
};
```
## Keyboard Navigation
- **Arrow Keys**: Navigate through mention options
- **Enter**: Select highlighted option
- **Escape**: Close mention dropdown
- **Tab**: Navigate through options and select
- **Backspace**: Navigate into mention chips
## Advanced Features
### Function Values
Options can have function values that execute when selected, useful for actions like sending messages or clearing input.
### Auto-Conversion
When `autoConvertMentions` is enabled, the component automatically converts text mentions to chips when users type space or press Enter.
### Paste Handling
The component intelligently parses mentions from pasted content, converting them to chips automatically.
### Rich Text Support
Mentions are displayed as styled chips within the contentEditable interface, providing a rich text experience.
## Examples Directory
Explore complete examples in the following directories:
- [simple](https://github.com/Alexanderdunlop/mentis/tree/main/packages/examples/simple)
- [styling](https://github.com/Alexanderdunlop/mentis/tree/main/packages/examples/styling)
- [tailwind](https://github.com/Alexanderdunlop/mentis/tree/main/packages/examples/tailwind)
- [nextjs](https://github.com/Alexanderdunlop/mentis/tree/main/packages/examples/nextjs)
## License
MIT © [Alexander Dunlop](https://github.com/alexanderdunlop)
