Mentions

Component

Interactive examples and API documentation

Basic
Single-line input (rows: nil or 1) vs multi-line textarea (rows: 2+).
Single-line (like Input)
rows: nil or 1 renders a single-line input
Multi-line (like TextArea)
rows: 2+ renders a textarea
Code 
<%= render Hakumi::Space::Component.new(direction: :vertical, size: :large, block: true) do %>
  <%= render Hakumi::Card::Component.new do %>
    <%= render Hakumi::Space::Component.new(direction: :vertical, size: :small, block: true) do %>
      <%= render Hakumi::Typography::Text::Component.new(strong: true) do %>
        Single-line (like Input)
      <% end %>

      <%= render Hakumi::Mentions::Component.new(
        name: "mentions_single",
        placeholder: "Type @ to mention",
        options: ["Ada Lovelace", "Grace Hopper", "Linus Torvalds", "Yukihiro Matsumoto"]
      ) %>

      <%= render Hakumi::Typography::Text::Component.new(type: :secondary, size: :small) do %>
        rows: nil or 1 renders a single-line input
      <% end %>
    <% end %>
  <% end %>

  <%= render Hakumi::Card::Component.new do %>
    <%= render Hakumi::Space::Component.new(direction: :vertical, size: :small, block: true) do %>
      <%= render Hakumi::Typography::Text::Component.new(strong: true) do %>
        Multi-line (like TextArea)
      <% end %>

      <%= render Hakumi::Mentions::Component.new(
        name: "mentions_multi",
        placeholder: "Type @ to mention someone",
        options: ["Ada Lovelace", "Grace Hopper", "Linus Torvalds", "Yukihiro Matsumoto"],
        rows: 4
      ) %>

      <%= render Hakumi::Typography::Text::Component.new(type: :secondary, size: :small) do %>
        rows: 2+ renders a textarea
      <% end %>
    <% end %>
  <% end %>
<% end %>
Multiple Prefixes
Support multiple triggers and adjust filtering behavior.
Code 
<%= render Hakumi::Card::Component.new do %>
  <%= render Hakumi::Mentions::Component.new(
    name: "mentions_prefixes",
    label: "Project Notes",
    placeholder: "Use @ for people or # for tags",
    prefix: ["@", "#"],
    split: " ",
    filter_option: :starts_with,
    options: ["@alice", "@bob", "#frontend", "#rails"],
    rows: 3,
    standalone: false
  ) %>
<% end %>
Sizes
Three sizes for single-line input: small, default, and large. Size only applies when rows is nil or 1.

Size only applies to single-line input (when rows is nil or 1). For textareas (rows >= 2), size is ignored.

Code 
<%= render Hakumi::Space::Component.new(direction: :vertical, size: :large) do %>
  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_small,
    label: "Small",
    placeholder: "Small size mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    size: :small,
    standalone: false
  ) %>

  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_default,
    label: "Default",
    placeholder: "Default size mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    size: :default,
    standalone: false
  ) %>

  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_large,
    label: "Large",
    placeholder: "Large size mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    size: :large,
    standalone: false
  ) %>
<% end %>

<style>
  .demo-description {
    color: var(--color-text-secondary);
    font-size: 14px;
    margin-bottom: 16px;
  }
</style>

<p class="demo-description">
  Size only applies to single-line input (when rows is nil or 1). For textareas (rows >= 2), size is ignored.
</p>
Variants
Three visual styles: outlined (default), borderless, and filled.
Code 
<%= render Hakumi::Space::Component.new(direction: :vertical, size: :large) do %>
  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_outlined,
    label: "Outlined (default)",
    placeholder: "Type @ to mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    variant: :outlined,
    standalone: false
  ) %>

  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_borderless,
    label: "Borderless",
    placeholder: "Type @ to mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    variant: :borderless,
    standalone: false
  ) %>

  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_filled,
    label: "Filled",
    placeholder: "Type @ to mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    variant: :filled,
    standalone: false
  ) %>
<% end %>
Status
Set validation status with error or warning states.
Code 
<%= render Hakumi::Space::Component.new(direction: :vertical, size: :large) do %>
  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_default,
    label: "Default",
    placeholder: "Type @ to mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    rows: 3
  ) %>

  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_error,
    label: "Error status",
    placeholder: "Type @ to mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    status: :error,
    rows: 3,
    caption: "This field has an error"
  ) %>

  <%= render Hakumi::Mentions::Component.new(
    name: :mentions_warning,
    label: "Warning status",
    placeholder: "Type @ to mention",
    options: ["Ada Lovelace", "Grace Hopper", "Margaret Hamilton"],
    status: :warning,
    rows: 3,
    caption: "This field has a warning"
  ) %>
<% end %>
States
Disabled and readonly states for mentions inputs.
Code 
<%= render Hakumi::Card::Component.new do %>
  <%= render Hakumi::Space::Component.new(direction: :vertical, size: :middle, block: true) do %>
    <%= render Hakumi::Mentions::Component.new(
      name: "mentions_disabled",
      label: "Disabled",
      placeholder: "Disabled mentions",
      options: ["Ada", "Grace"],
      disabled: true,
      rows: 3,
      standalone: false
    ) %>

    <%= render Hakumi::Mentions::Component.new(
      name: "mentions_readonly",
      label: "Readonly",
      value: "@Ada Lovelace",
      options: ["Ada", "Grace"],
      readonly: true,
      rows: 3,
      standalone: false
    ) %>
  <% end %>
<% end %>
Auto Size
Let the textarea grow with content.
Code 
<%= render Hakumi::Card::Component.new do %>
  <%= render Hakumi::Mentions::Component.new(
    name: "mentions_auto",
    label: "Autosize",
    placeholder: "Type multiple lines to resize",
    options: ["Ada", "Grace", "Linus"],
    auto_size: true,
    rows: 2,
    standalone: false
  ) %>
<% end %>
Smart Positioning
The dropdown appears right below the @ symbol at cursor position, not below the entire textarea. Follows Ant Design's behavior.
Dynamic Dropdown Positioning
The dropdown appears right below the @ symbol, not below the entire textarea. Try typing @ at different positions to see it follow your cursor!
Code 
<%= render Hakumi::Card::Component.new do %>
  <%= render Hakumi::Space::Component.new(direction: :vertical, size: :small, block: true) do %>
    <%= render Hakumi::Typography::Text::Component.new(strong: true) do %>
      Dynamic Dropdown Positioning
    <% end %>

    <%= render Hakumi::Mentions::Component.new(
      name: "mentions_positioning",
      placeholder: "Try typing @ at different positions in the text...",
      options: ["Ada Lovelace", "Grace Hopper", "Linus Torvalds", "Yukihiro Matsumoto", "Alan Turing", "Margaret Hamilton"],
      rows: 6,
      value: "Hello world!\n\nType @ here to see the dropdown appear at cursor position.\n\nOr type @ at the end."
    ) %>

    <%= render Hakumi::Typography::Text::Component.new(type: :secondary, size: :small) do %>
      The dropdown appears right below the @ symbol, not below the entire textarea. Try typing @ at different positions to see it follow your cursor!
    <% end %>
  <% end %>
<% end %>
Rails Form Builder
Seamless integration with Rails forms using form.mentions_field with automatic label, validation, and error handling.
Type @ to mention someone
Code 
<%= render Hakumi::Card::Component.new do %>
  <%# Ejemplo de integración con Rails FormBuilder %>
  <%= hakumi_form_with(url: "#", method: :post) do |f| %>
    <%= f.mentions_field :comment,
      options: ["Ada Lovelace", "Grace Hopper", "Linus Torvalds", "Yukihiro Matsumoto"],
      label: "Comment",
      caption: "Type @ to mention someone",
      placeholder: "Share your thoughts...",
      rows: 4
    %>

    <%= f.submit "Post Comment" %>
  <% end %>
<% end %>

<style>
  .hakumi-button[type="submit"] {
    margin-top: 16px;
  }
</style>

Mentions API

Prop Type Default Description
name String or Symbol required Name/id for the textarea.
value String nil Controlled value for the textarea.
default_value String nil Initial value used when value is nil.
options Array [] Suggestions list (strings, arrays, or hashes).
prefix String or Array @ Prefix triggers for mentions.
split String " " Token separator used to detect mentions.
filter_option Symbol :contains Filtering mode (:contains or :starts_with).
placeholder String nil Textarea placeholder.
disabled Boolean false Disable interactions.
readonly Boolean false Make the textarea readonly.
required Boolean false Add required attribute to textarea.
rows Integer nil Visible row count. nil or 1 renders single-line input, 2+ renders textarea.
auto_size Boolean false Auto-resize the textarea height (only for rows >= 2).
size Symbol :default Input size (:small, :default, :large). Only applies when rows is nil or 1.
variant Symbol :outlined Visual style (:outlined, :borderless, :filled).
status Symbol nil Validation status (:error, :warning, or nil).
label String nil Form label (when standalone is false).
caption String nil Help text (when standalone is false).
errors Array [] Validation errors (when standalone is false).
standalone Boolean true Render without form item wrapper.
**html_options Keyword args - Extra attributes merged into the wrapper.

JavaScript API (element.hakumiComponent.api)

Prop Type Default Description
getValue() Function - Returns the current textarea value.
setValue(value) Function - Sets the textarea value.
getMentions() Function - Returns parsed mentions without prefixes.
focus() Function - Focuses the textarea.
blur() Function - Blurs the textarea.
insertMention(value) Function - Inserts a mention at the cursor position.

Events

Prop Type Default Description
hakumi:mentions:change CustomEvent - Fired on input. Detail: { value, mentions }.
hakumi:mentions:select CustomEvent - Fired after selecting a suggestion. Detail: { value, label }.
hakumi:mentions:search CustomEvent - Fired when filtering suggestions. Detail: { query, prefix }.