Dropdown

Native popover menus with typed triggers, entries, placement, and keyboard state.

Source: app/components/nitro_kit/dropdown.rb
API: NitroKit::Dropdown.new(id:) { |menu| menu.trigger; menu.item }

Rubytest/dummy/app/components/gallery/components/dropdown_page.rb

NitroKit::Dropdown::PLACEMENTS.each do |placement|
  sample(placement.to_s.humanize, slug: placement.to_s) do
    render_menu("gallery-dropdown-#{placement}", placement:) do |menu|
      menu.item("Open profile", href: "/gallery/profile")
      menu.item("Copy account ID")
    end
  end
end

Rubytest/dummy/app/components/gallery/components/dropdown_page.rb

render NitroKit::Dropdown.new(id: "gallery-dropdown-account") do |menu|
  menu.trigger("Account actions", variant: :primary)
  menu.title("Workspace")
  menu.item("Workspace settings", href: "/gallery/settings")
  menu.item("Duplicate workspace")
  menu.item("Export audit log", disabled: true)
  menu.separator
  menu.title("Danger zone")
  menu.item("Delete workspace", variant: :destructive)
end

Rubytest/dummy/app/components/gallery/components/dropdown_page.rb

sample("Icon-only trigger", slug: "icon-only-trigger") do
  render NitroKit::Dropdown.new(id: "gallery-dropdown-overflow", placement: :bottom_end) do |menu|
    menu.trigger(icon: :ellipsis, label: "Record actions", variant: :ghost)
    menu.item("Rename record", icon: :pencil)
    menu.item("Duplicate record", icon: :copy)
    menu.separator
    menu.item("Delete record", icon: :trash_2, variant: :destructive)
  end
end
sample("Trailing trigger icon", slug: "trailing-trigger-icon") do
  render NitroKit::Dropdown.new(id: "gallery-dropdown-sort") do |menu|
    menu.trigger("Sort by", icon_end: :chevron_down)
    menu.item("Newest first", icon: :arrow_down)
    menu.item("Oldest first", icon: :arrow_up)
  end
end

Rubytest/dummy/app/components/gallery/components/dropdown_page.rb

sample("Disabled trigger", slug: "disabled-trigger") do
  render NitroKit::Dropdown.new(id: "gallery-dropdown-disabled") do |menu|
    menu.trigger("Actions unavailable", disabled: true)
    menu.item("Unavailable action", disabled: true)
  end
end
sample("Long content", slug: "long-content") do
  render NitroKit::Dropdown.new(id: "gallery-dropdown-long") do |menu|
    menu.trigger("Deployment actions")
    menu.item("Promote the currently verified release to production")
    menu.item("Restore the previously healthy production release", variant: :destructive)
  end
end

Rubytest/dummy/app/components/gallery/components/dropdown_page.rb

render NitroKit::Card.new(id: "gallery-dropdown-deployment-card") do |card|
  card.title("Release 2026.07.13", level: 3)
  card.body do
    render NitroKit::Badge.new(
      "Healthy",
      id: "gallery-dropdown-deployment-status",
      color: :success,
      size: :sm
    )
    p { "Serving all workspaces from fra1 and iad1." }
  end
  card.footer do
    render NitroKit::Dropdown.new(id: "gallery-dropdown-deployment") do |menu|
      menu.trigger("Release actions", variant: :ghost)
      menu.item("View deployment", href: "/gallery/deployments/2026-07-13")
      menu.item("Copy release identifier")
      menu.separator
      menu.item("Roll back release", variant: :destructive)
    end
  end
end

Component contract

Constructor options, rendered root, closed vocabularies, and compound boundary for this component, exactly as shipped.

docs/component_contracts.md · NitroKit::Dropdown

Constructor-specific options: id: nil, placement: :bottom_start
Root and closed vocabulary: div[data-nk=dropdown]; placements bottom_start bottom_end top_start top_end; item variants default destructive; item types button submit reset
Compound contract: Requires a declaration block, exactly one trigger, and at least one item. id: defaults to a generated nk-dropdown-* identifier and otherwise follows the shared fragment-safe identifier contract. trigger(text = nil, variant:, size:, icon:, icon_end:, label:, disabled:) forwards to Button, so an icon-only trigger keeps square icon-only geometry; variant: and size: are validated against Button vocabularies when the trigger is declared. item(text = nil, href:, icon:, variant:, type:, disabled:) renders an optional dropdown-item-icon slot and emits the owned data-variant on the item slot, matching the Toast::Item precedent; caller data-variant stays reserved. The native popover=auto owns open state and implicit invoker relationships. Optional visual titles are presentational to the menu accessibility tree; separators remain native. A small controller adds menu focus navigation, native outside-pointer dismissal fallback for capable Popover engines, and focus restoration without mirroring state. The fallback ignores composed-path interactions inside the trigger or menu and releases its listener on every close and disconnect.

System rules for coding agents

Instructions for coding agents, repeated on every component page so one fetched page has enough context. Humans can usually skip this section.

test/dummy/app/components/gallery/agent_rules.rb

View agent instructions

Nitro Kit 2.0 is a gem-owned, Phlex-only UI system for Rails. Render components directly: render NitroKit::Button.new("Save", variant: :primary).
Compose Nitro components inside application-owned Phlex classes. Public initializers and declared slots are the component API; private methods are not.
Public options are explicit keywords, and enumerated options are closed vocabularies. Invalid names or values raise ArgumentError; this component's accepted options are in the contract above.
Pass native attributes through their typed boundary: html: for HTML, aria: for ARIA, and data: for application data. class and style are forbidden, including inside html:.
Nitro owns NitroKit::Component::RESERVED_DATA_ATTRIBUTES: data-nk, data-slot, data-variant, data-size, data-nk-escape, data-enhanced, data-state, data-disabled, data-required, data-orientation, data-presentation, data-placement, data-layout, data-side, data-field-type, data-dir, data-gap, data-align, data-justify, data-wrap, data-cols, data-mode, data-key. Do not pass them through data:. data-action, data-controller are additive and compose with Nitro behavior.
If an integration truly requires a class, use desperately_need_a_class:. It requires a non-blank String and marks the exception with data-nk-escape="class".
Every root emits data-nk; owned parts emit component-qualified data-slot values such as field-control or card-title. Select on those attributes, never on classes.
Customize components with documented --nk-* custom properties in an application stylesheet. Variables beginning with --_nk-* are private component mechanics.
Use NitroKit::Flex and NitroKit::Grid for layout. Parents own external placement and available width; components own their intrinsic geometry.
Preserve native elements and accessibility semantics. State is exposed through native semantics and ARIA first, and through data-state when styling or behavior also needs it.