Button

Native buttons and links with typed variants, sizes, and icons.

Source: app/components/nitro_kit/button.rb
API: NitroKit::Button.new(text, variant:, size:, icon:, submission_indicator:)

Variants

Every visual intent uses the same native button contract.

Variant matrix

Default

Primary

Destructive

Ghost

ViewportFull width

Width

Preset

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

sample("Default", slug: "default") do
  render NitroKit::Button.new("Default", id: "gallery-button-variant-default")
end
sample("Primary", slug: "primary") do
  render NitroKit::Button.new(
    "Primary",
    id: "gallery-button-variant-primary",
    variant: :primary,
    icon: :save
  )
end
sample("Destructive", slug: "destructive") do
  render NitroKit::Button.new(
    "Destructive",
    id: "gallery-button-variant-destructive",
    variant: :destructive,
    icon: :trash_2
  )
end
sample("Ghost", slug: "ghost") do
  render NitroKit::Button.new(
    "Ghost",
    id: "gallery-button-variant-ghost",
    variant: :ghost
  )
end

Sizes

Five closed sizes cover compact controls through high-emphasis calls to action.

Size scale

Extra small

Small

Medium

Large

Extra large

ViewportFull width

Width

Preset

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

Gallery::Data.button_sizes.each do |button|
  sample(button.label, slug: button.slug) do
    render_button(button, id: "gallery-button-size-#{button.slug}")
  end
end

Content modes

Text, leading and trailing icons, icon-only controls, links, and block labels stay explicit.

Content combinations

Leading icon

Trailing icon

Icon only

Link

Read documentation

Block label

Long label

Avatar and label

Default avatar and label

Viewport640 px · sm

Width

Preset

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

sample("Leading icon", slug: "leading-icon") do
  render NitroKit::Button.new(
    "Save report",
    id: "gallery-button-leading-icon",
    icon: :save,
    variant: :primary
  )
end
sample("Trailing icon", slug: "trailing-icon") do
  render NitroKit::Button.new(
    "Continue",
    id: "gallery-button-trailing-icon",
    icon_end: :arrow_right
  )
end
sample("Icon only", slug: "icon-only") do
  render NitroKit::Button.new(
    id: "gallery-button-icon-only",
    icon: :x,
    variant: :ghost,
    aria: { label: "Close notification" }
  )
end
sample("Link", slug: "link") do
  render NitroKit::Button.new(
    "Read documentation",
    id: "gallery-button-link",
    href: "#button-documentation",
    icon_end: :arrow_right
  )
end
sample("Block label", slug: "block-label") do
  render NitroKit::Button.new(id: "gallery-button-block-label") do
    "Label supplied by a Phlex block"
  end
end
sample("Long label", slug: "long-label") do
  render NitroKit::Button.new(
    "Download the complete workspace activity archive",
    id: "gallery-button-long-label",
    icon: :download
  )
end
sample("Avatar and label", slug: "avatar-label") do
  render NitroKit::Button.new(id: "gallery-button-avatar", size: :xs) do
    render NitroKit::Avatar.new(
      src: "/icon.svg",
      decorative: true,
      fallback: "NK",
      size: :xs
    )
    plain "Nitro Kit"
  end
end
sample("Default avatar and label", slug: "default-avatar-label") do
  render NitroKit::Button.new(id: "gallery-button-avatar-default") do
    render NitroKit::Avatar.new(
      src: "/icon.svg",
      decorative: true,
      fallback: "NK"
    )
    plain "Open workspace"
  end
end

Native states

Disabled controls retain visible state while links lose navigation and expose ARIA disabled.

Loading

Viewport640 px · sm

Width

Preset

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

render NitroKit::Button.new(
  "Deploying",
  id: "gallery-button-loading",
  variant: :primary,
  icon: :rocket,
  loading: true
)
render NitroKit::Button.new(
  id: "gallery-button-loading-icon-only",
  icon: :refresh_cw,
  label: "Refreshing deployments",
  loading: true
)

Enabled and disabled

Available link Unavailable link

Viewport640 px · sm

Width

Preset

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

render NitroKit::Button.new(
  "Submit invoice",
  id: "gallery-button-submit",
  type: :submit,
  variant: :primary
)
render NitroKit::Button.new(
  "Delete workspace",
  id: "gallery-button-disabled",
  variant: :destructive,
  disabled: true
)
render NitroKit::Button.new(
  "Available link",
  id: "gallery-button-link-enabled",
  href: "#button-enabled"
)
render NitroKit::Button.new(
  "Unavailable link",
  id: "gallery-button-link-disabled",
  href: "#button-disabled",
  disabled: true
)

Turbo submission feedback

Submission keeps the original label, dims immediately, and can opt into a spinner that expands the button after 1 second.

Dim only

Spinner after 1 second

Viewport640 px · sm

Width

Preset

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

sample("Dim only", slug: "dim-only") do
  form_with(
    url: gallery_button_submission_path,
    builder: NitroKit::FormBuilder,
    id: "gallery-button-turbo-form"
  ) do |form|
    form.submit(
      "Save workspace changes",
      id: "gallery-button-turbo-submit",
      data: { turbo_submits_with: "Saving…" }
    )
  end
end
sample("Spinner after 1 second", slug: "delayed-spinner") do
  form_with(
    url: gallery_button_submission_path,
    builder: NitroKit::FormBuilder,
    id: "gallery-button-turbo-spinner-form"
  ) do |form|
    form.submit(
      "Save workspace changes",
      id: "gallery-button-turbo-spinner-submit",
      submission_indicator: :spinner,
      data: { turbo_submits_with: "Saving…" }
    )
  end
end

Component contract

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

docs/component_contracts.md · NitroKit::Button

Constructor-specific options: optional text or block
href: nil, variant: :default, size: :md, icon: nil, icon_end: nil, label: nil, id: nil, type: :button, name: nil, value: nil, form: nil, target: nil, rel: nil, download: nil, disabled: false, loading: false, submission_indicator: nil
Root and closed vocabulary: native button or a[data-nk=button]; variants default primary destructive ghost; sizes xs sm md lg xl; types button submit reset
Compound contract: Requires text, a block, or an icon. default is the ordinary action treatment; ghost is reserved for deliberately low-emphasis interface chrome, not routine secondary actions. Icon-only buttons require label:, aria: { label: }, or aria: { labelledby: }; label: and aria: { label: } are the same attribute and collide. icon_end: matches the button-icon-end slot. Blank text, treatment vocabularies, and link/button option mixing raise on construction; text-plus-block and the icon-only accessible name raise at render because only render time knows whether a block supplies the label. type: applies to native buttons only and raises when combined with href:. loading: true disables the control, sets aria-busy="true", and replaces the leading icon with the button-spinner slot. Disabled links lose href, receive aria-disabled, and leave the tab order. submission_indicator: :spinner applies only to native submit Buttons, cannot combine with loading:, and renders the button-submission-spinner slot that nk--button reveals during a slow Turbo submission.

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.