Radio button

Same-name native radio choices with explicit labels, values, sizes, and state.

Source: app/components/nitro_kit/radio_button.rb
API: NitroKit::RadioButton.new(label:, id:, name:, value:, checked:, size:)

Native selection

Radio buttons share a native name and the browser owns selection; nothing mirrors checked state into markup.

Workspace visibility

Private to invited members

Visible to the organization

Public on the web

Viewport640 px · sm

Width

Preset

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

render NitroKit::RadioButton.new(
  label: "Private to invited members",
  id: "gallery-radio-button-private-control",
  name: "workspace[visibility]",
  value: "private",
  checked: true,
  required: true,
  html: { id: "gallery-radio-button-private" }
)
render NitroKit::RadioButton.new(
  label: "Visible to the organization",
  id: "gallery-radio-button-organization-control",
  name: "workspace[visibility]",
  value: "organization",
  required: true,
  html: { id: "gallery-radio-button-organization" }
)
render NitroKit::RadioButton.new(
  label: "Public on the web",
  id: "gallery-radio-button-public-control",
  name: "workspace[visibility]",
  value: "public",
  disabled: true,
  required: true,
  html: { id: "gallery-radio-button-public" }
)

Size and label pressure

Both sizes, explicitly named standalone controls, disabled state, and long labels preserve native radio semantics.

State matrix

Medium

Member

Large

Administrator

Standalone

Invalid

Unsupported region

Long label

Retain audit events and credential activity for the extended regulated compliance period

Viewport640 px · sm

Width

Preset

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

sample("Medium", slug: "medium") do
  render NitroKit::RadioButton.new(
    label: "Member",
    id: "gallery-radio-button-medium-control",
    name: "member[role]",
    value: "member",
    checked: true,
    size: :md,
    html: { id: "gallery-radio-button-medium" }
  )
end
sample("Large", slug: "large") do
  render NitroKit::RadioButton.new(
    label: "Administrator",
    id: "gallery-radio-button-large-control",
    name: "member[role]",
    value: "admin",
    size: :lg,
    html: { id: "gallery-radio-button-large" }
  )
end
sample("Standalone", slug: "standalone") do
  render NitroKit::RadioButton.new(
    id: "gallery-radio-button-standalone-control",
    name: "table[selection]",
    value: "deployment-1842",
    control_aria: { label: "Select deployment 1842" },
    html: { id: "gallery-radio-button-standalone" }
  )
end
sample("Invalid", slug: "invalid") do
  render NitroKit::RadioButton.new(
    label: "Unsupported region",
    id: "gallery-radio-button-invalid-control",
    name: "deployment[region]",
    value: "unsupported",
    checked: true,
    invalid: true,
    html: { id: "gallery-radio-button-invalid" }
  )
end
sample("Long label", slug: "long") do
  render NitroKit::RadioButton.new(
    label: "Retain audit events and credential activity for the extended regulated compliance period",
    id: "gallery-radio-button-long-control",
    name: "retention[policy]",
    value: "regulated",
    html: { id: "gallery-radio-button-long" }
  )
end

Rails form builder

Individual builder radio helpers preserve Rails naming and explicit accessible names. These radios are deliberately ARIA-only: each control is named through aria-label for dense surfaces such as a table selection column, so no visible label text renders.

Invitation role

Viewport640 px · sm

Width

Preset

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

invitation = Gallery::FormExamples.team_invitation

form_with(
  model: invitation,
  scope: :invitation,
  url: "#invitation-role",
  builder: NitroKit::FormBuilder,
  id: "gallery-radio-button-invitation-form"
) do |form|
  form.group do
    form.radio_button(
      :role,
      "admin",
      id: "gallery-radio-button-builder-admin",
      aria: { label: "Administrator" }
    )
    form.radio_button(
      :role,
      "member",
      id: "gallery-radio-button-builder-member",
      aria: { label: "Member" }
    )
    form.radio_button(
      :role,
      "viewer",
      id: "gallery-radio-button-builder-viewer",
      aria: { label: "Viewer" },
      disabled: true
    )
  end
end

Under pressure

Every hostile identity from Gallery::Hostile as a same-name radio label with sentence and URL descriptions, then a required radio that is also disabled and invalid under a paragraph-length label.

Hostile labels

Viewport640 px · sm

Width

Preset

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

render NitroKit::Flex.new(dir: :col, gap: 3, align: :stretch) do
  Gallery::Hostile::NAMES.each_with_index do |name, index|
    render NitroKit::RadioButton.new(
      label: name,
      description: index.even? ? Gallery::Hostile::LONG_SENTENCE : Gallery::Hostile::LONG_URL,
      id: "gallery-radio-button-hostile-#{index}-control",
      name: "hostile[identity]",
      value: "hostile_#{index}",
      checked: index.zero?,
      size: index.odd? ? :lg : :md,
      html: { id: "gallery-radio-button-hostile-#{index}" }
    )
  end
  render NitroKit::RadioButton.new(
    label: Gallery::Hostile::LONG_PARAGRAPH,
    description: Gallery::Hostile::LONG_ERROR,
    id: "gallery-radio-button-hostile-locked-control",
    name: "hostile[identity]",
    value: "hostile_locked",
    required: true,
    disabled: true,
    invalid: true,
    html: { id: "gallery-radio-button-hostile-locked" }
  )
end

Component contract

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

docs/component_contracts.md · NitroKit::RadioButton

Constructor-specific options: label: nil, description: nil, id: nil, name: nil, value: "1", checked: false, disabled: false, required: false, invalid: false, size: :md, control_html: {}, control_aria: {}, control_data: {}
Root and closed vocabulary: div[data-nk=radio-button] containing a native radio input; sizes md lg
Contract: Requires label text, block content, or an accessible control name; a description requires a label or block and a non-blank String id:, renders outside the label in the radio-button-description slot, and binds aria-describedby. invalid: true sets aria-invalid on the control. Selection is entirely native: no Stimulus controller and no mirrored data-state.

Relevant patterns

Application conventions this component belongs to. Each summary is the leading section of its pattern document.

docs/patterns/resource_form.md

Resource form

One model-backed Phlex component renders initial and invalid states.
Rails owns names, values, and errors; Nitro owns presentation.
Invalid mutations render the same model with 422; success redirects with 303.
Use one primary submit: the shell toolbar owns it, or a standalone form keeps it inside form.group.
Wrap the form in a Turbo Frame only when it needs an independent lifecycle.

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.