React Mention Textarea

A powerful React component for @ mentions with multi-layer navigation, search functionality, and custom action cards. Built with TypeScript and designed for Tailwind CSS.

Features

• 🎯 Smart Detection - Automatically detects @ symbols and shows contextual menus
• 🔍 Real-time Search - Filter items as you type with fuzzy matching
• ⌨️ Keyboard Navigation - Full keyboard support (arrows, Enter, Escape, Tab)
• 📱 Multi-layer Menus - Navigate through nested menus with breadcrumb support
• ⚡ Action Cards - Custom action cards for complex interactions
• 🎨 Customizable Themes - Built-in light/dark mode support
• 🚀 TypeScript First - Full type definitions included
• 📦 Zero Dependencies - Only requires React as peer dependency
• 🔗 Source-Aware - Provides structured data for API integration

Installation

From GitHub Packages

npm install @rohan-krishna/react-mention-textarea

From GitHub Repository

npm install github:rohan-krishna/react-mention-textarea

Quick Start

import React, { useState } from 'react';
import { MentionTextarea, MentionConfig } from '@rohan-krishna/react-mention-textarea';

const users = [
  { id: '1', label: 'John Doe', type: 'user', icon: '👤' },
  { id: '2', label: 'Jane Smith', type: 'user', icon: '👤' },
];

const mentions: MentionConfig[] = [
  {
    trigger: '@',
    data: users
  }
];

function App() {
  const [text, setText] = useState('');

  return (
    <MentionTextarea
      value={text}
      onChange={setText}
      mentions={mentions}
      placeholder="Type @ to mention someone..."
    />
  );
}

Advanced Usage

Multi-layer Navigation

const multiLayerMentions: MentionConfig[] = [
  {
    trigger: '@',
    data: [
      {
        id: 'users',
        label: 'Users',
        icon: '👥',
        children: [
          { id: '1', label: 'John Doe', type: 'user' },
          { id: '2', label: 'Jane Smith', type: 'user' },
        ]
      },
      {
        id: 'actions',
        label: 'Actions',
        icon: '⚡',
        children: [
          {
            id: 'create_notion',
            label: 'Create Notion Page',
            component: 'NotionPageCard'
          }
        ]
      }
    ]
  }
];

Multiple Triggers

const advancedMentions: MentionConfig[] = [
  {
    trigger: '@',
    data: users
  },
  {
    trigger: '#',
    data: tags
  },
  {
    trigger: '/',
    data: commands
  }
];

Custom Action Cards

import { ActionCardProps } from '@rohan-krishna/react-mention-textarea';

const CustomActionCard: React.FC<ActionCardProps> = ({ item, onSubmit, onCancel }) => {
  const [title, setTitle] = useState('');

  const handleSubmit = () => {
    onSubmit(`[Custom: ${title}]`);
  };

  return (
    <div className="p-4">
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Enter title..."
      />
      <button onClick={handleSubmit}>Submit</button>
      <button onClick={onCancel}>Cancel</button>
    </div>
  );
};

API Reference

MentionTextarea Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | string | - | Current textarea value | | onChange | (value: string) => void | - | Value change handler | | mentions | MentionConfig[] | - | Mention configurations | | placeholder | string | 'Type @ to mention...' | Textarea placeholder | | className | string | '' | Additional CSS classes | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Theme mode | | maxMenuHeight | number | 300 | Maximum menu height in pixels | | disabled | boolean | false | Disable the textarea | | rows | number | 4 | Number of textarea rows | | autoFocus | boolean | false | Auto-focus on mount | | onMentionSelect | (item: MentionItem, text: string) => void | - | Mention selection callback |

MentionConfig

interface MentionConfig {
  trigger: string;                    // Trigger character (e.g., '@', '#')
  data: MentionItem[];               // Available items
  renderItem?: (item: MentionItem) => React.ReactNode;  // Custom item renderer
  onSelect?: (item: MentionItem) => string;             // Custom selection handler
  searchPlaceholder?: string;        // Search input placeholder
  maxResults?: number;               // Maximum results to show
}

MentionItem

interface MentionItem {
  id: string;                        // Unique identifier
  label: string;                     // Display text
  type?: 'user' | 'source' | 'action' | 'reference';  // Item type
  icon?: string;                     // Icon (emoji or text)
  avatar?: string;                   // Avatar image URL
  description?: string;              // Additional description
  children?: MentionItem[];          // Sub-items for navigation
  component?: string;                // Custom component name
  action?: (params?: any) => string | Promise<string>;  // Custom action
  metadata?: Record<string, any>;    // Additional data
}

Keyboard Shortcuts

| Key | Action | |-----|--------| | ↑ / ↓ | Navigate through items | | Enter | Select item or navigate to sub-menu | | ← | Navigate back to previous menu level | | Escape | Close menu | | Tab | Close menu and continue |

Styling

The component is designed to work with Tailwind CSS. All styles use Tailwind classes and CSS custom properties for theming.

Custom Themes

<MentionTextarea
  theme="dark"
  className="custom-textarea"
  // ... other props
/>

CSS Variables

:root {
  --mention-bg: #ffffff;
  --mention-border: #e5e7eb;
  --mention-text: #111827;
  --mention-hover: #f3f4f6;
  --mention-selected: #dbeafe;
}

[data-theme="dark"] {
  --mention-bg: #1f2937;
  --mention-border: #374151;
  --mention-text: #f9fafb;
  --mention-hover: #374151;
  --mention-selected: #1e3a8a;
}

Development

Building the Package

cd components/mention-textarea
npm install
npm run build

Publishing to GitHub Packages

See PUBLISHING.md for detailed instructions.

Using in Other Projects

npm install @rohan-krishna/react-mention-textarea

import { MentionTextarea } from '@rohan-krishna/react-mention-textarea';

Examples

Check out the demo in the main project to see all features in action:

• Basic @ mentions
• Multi-layer navigation
• Multiple triggers
• Custom action cards
• Keyboard navigation
• Search functionality

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• � Package: GitHub Packages