React Mentions Input Component

Common errors

• Uncaught Error: MentionsInput needs to have a Mention child

  cause The `MentionsInput` component was rendered without any `Mention` child components. Each `MentionsInput` must define at least one `Mention` to specify triggers and data sources.
  fix Add at least one `<Mention trigger="@" data={yourDataSource} />` child inside your `<MentionsInput>` component.

• Error: Invalid prop `data` supplied to `Mention`. Expected an array or a function, but received [object Object].

  cause The `data` prop of a `Mention` component received an object instead of an array of suggestions or a function that fetches suggestions.
  fix Ensure the `data` prop is either an array of objects (e.g., `[{ id: 'id', display: 'Name' }]`) or a function that takes a `query` string and a `callback` function.

• ReferenceError: require is not defined (when using import { MentionsInput } from 'react-mentions')

  cause This error typically occurs in environments that only support ES Modules (ESM) when a CommonJS `require()` call is made implicitly by a bundler or explicitly in the code, or when a bundler incorrectly transpiles ESM imports to CJS `require` calls without proper environment configuration.
  fix Ensure your project is configured for ES Modules. If using an older React setup or specific testing frameworks, you might need to adjust Babel/Webpack configurations to correctly handle ESM. For `react-mentions`, always use `import { MentionsInput, Mention } from 'react-mentions'` in modern React projects.

Warnings

• breaking The `autofocus` attribute was removed from the underlying textarea by default in `v4.4.10`. If your application relied on the input automatically gaining focus upon component mount, you will need to manually manage focus, for example using `inputRef` and `ref.current.focus()` within a `useEffect` hook.
  Fix: Use the `inputRef` prop on `MentionsInput` to get a ref to the underlying HTML element, and then imperatively call `inputRef.current.focus()` when needed, e.g., in a `useEffect` hook with an empty dependency array for initial mount.
• gotcha Styling `react-mentions` requires understanding how the component renders its internal structure (a hidden 'highlighter' div mirroring the input content). Directly targeting the input or its container with global styles may lead to misalignments or unexpected visual behavior. It's recommended to use the `style` prop for granular control or carefully scope CSS classes.
  Fix: Refer to the `react-mentions` documentation for the recommended CSS structure and prop-based styling (e.g., `style` prop for `MentionsInput` and `suggestions`). Avoid overly aggressive global CSS rules that might interfere with its internal layout.
• gotcha When using `suggestionsPortalHost`, ensure that the host element exists in the DOM at the time the `MentionsInput` component mounts, or handle its dynamic availability. Incorrect setup can lead to suggestions not rendering or appearing in unexpected locations.
  Fix: Provide a valid DOM element to `suggestionsPortalHost` (e.g., `document.body` or a specific `div` element). If the host is dynamically rendered, ensure the `MentionsInput` re-renders or updates its portal when the host becomes available. Consider using `React.createRef` for the host element and passing `hostRef.current`.
• gotcha The `onChange` callback provides four arguments: `event`, `newValue`, `newPlainTextValue`, and `mentions`. Developers often only use `newValue` and might miss `newPlainTextValue` which provides the string without markup, or `mentions` which is an array of detected mention objects. Misunderstanding these can lead to incorrect data handling.
  Fix: Always destructure or access all relevant arguments from the `onChange` callback: `(event, newValue, newPlainTextValue, mentions) => { /* use all here */ }`. Use `newValue` for storing the rich-text content, and `newPlainTextValue` for display purposes where markup is undesirable.
• gotcha When `allowSpaceInQuery` is set to `true`, the suggestion list will remain open even if the user types spaces, which might be an unexpected UX for single-word queries. This prop is primarily for multi-word search queries within the suggestion context.
  Fix: Only set `allowSpaceInQuery={true}` if your mention data source truly supports multi-word searches (e.g., searching for 'John Doe'). For typical single-name mentions, keep it `false` (default) to close suggestions after a space, which is often more intuitive.

Install

• npm install react-mentions npm
• yarn add react-mentions yarn
• pnpm add react-mentions pnpm

Imports

• MentionsInput
  wrong:

  const MentionsInput = require('react-mentions').MentionsInput

  correct:

  import { MentionsInput } from 'react-mentions'

  Primary component for rendering the mentions-enabled textarea.
• Mention
  wrong:

  import Mention from 'react-mentions/lib/Mention'

  correct:

  import { Mention } from 'react-mentions'

  Child component of MentionsInput, used to define specific mention triggers and data sources. Do not import from sub-paths.
• MentionsInput (type)

  import type { MentionsInputProps } from 'react-mentions'

  Import types separately for stricter TypeScript checking.

Quickstart

This quickstart demonstrates a basic React Mentions setup, allowing users to type '@' to trigger suggestions for mentioning predefined users. It includes state management for the input value, a data source function for suggestions, and a custom suggestion renderer, showcasing how to integrate the component into a React application. Basic inline styles are provided for immediate visibility.

import React, { useState, useCallback } from 'react';
import { MentionsInput, Mention } from 'react-mentions';
import './index.css'; // Assuming some basic styling for .mentions, .mention, .suggestions

const defaultStyle = {
  control: {
    backgroundColor: '#fff',
    fontSize: 14,
    fontWeight: 'normal',
  },
  '&multiLine': {
    control: {
      minHeight: 63,
    },
    highlighter: {
      padding: 9,
      border: '1px solid transparent',
    },
    input: {
      padding: 9,
      border: '1px solid silver',
    },
  },
  suggestions: {
    list: {
      backgroundColor: '#fff',
      border: '1px solid rgba(0,0,0,0.15)',
      fontSize: 14,
    },
    item: {
      padding: '5px 15px',
      borderBottom: '1px solid rgba(0,0,0,0.15)',
      '&focused': {
        backgroundColor: '#cee4e5',
      },
    },
  },
};

function MentionsEditor() {
  const [value, setValue] = useState("Hello @[John Doe](john.doe) and @[Jane Smith](jane.smith)");

  const users = [
    { id: 'john.doe', display: 'John Doe' },
    { id: 'jane.smith', display: 'Jane Smith' },
    { id: 'mike.tyson', display: 'Mike Tyson' },
    { id: 'alice.wonder', display: 'Alice Wonderland' },
  ];

  const handleChange = useCallback((event, newValue, newPlainTextValue, mentions) => {
    setValue(newValue);
    console.log('New Value:', newValue);
    console.log('Plain Text:', newPlainTextValue);
    console.log('Mentions:', mentions);
  }, []);

  const fetchUsers = useCallback((query, callback) => {
    if (!query) return callback(users);
    const filteredUsers = users.filter(user =>
      user.display.toLowerCase().includes(query.toLowerCase())
    );
    callback(filteredUsers);
  }, [users]);

  return (
    <div className="editor-container">
      <h2>React Mentions Example</h2>
      <MentionsInput
        value={value}
        onChange={handleChange}
        style={defaultStyle} // Inline styles for quick demo, recommend external CSS
        placeholder="Type @ to mention someone..."
      >
        <Mention
          trigger="@"
          data={fetchUsers}
          renderSuggestion={(suggestion, search, highlightedDisplay) => (
            <div>
              {highlightedDisplay}
            </div>
          )}
        />
      </MentionsInput>
      <div style={{ marginTop: '20px', border: '1px solid #eee', padding: '10px' }}>
        <h3>Current Raw Input Value:</h3>
        <pre>{value}</pre>
      </div>
    </div>
  );
}

export default MentionsEditor;