sample("Medium off", slug:"medium-off") do
render NitroKit::Switch.new(
label:"Weekly digest",
description:"One summary every Monday morning.",
id:"gallery-switch-medium-control",
name:"preferences[weekly_digest]",
size::md,
html: { id:"gallery-switch-medium" }
)
end
sample("Large on", slug:"large-on") do
render NitroKit::Switch.new(
label:"Deployment alerts",
description:"Notify the operations channel after production deploys.",
id:"gallery-switch-large-control",
name:"preferences[deployment_alerts]",
checked:true,
size::lg,
html: { id:"gallery-switch-large" }
)
end
sample("Invalid", slug:"invalid") do
render NitroKit::Switch.new(
label:"Accept the processing agreement",
description:"Required before data exports can run.",
id:"gallery-switch-invalid-control",
name:"preferences[processing_agreement]",
invalid:true,
required:true,
html: { id:"gallery-switch-invalid" }
)
end
sample("Required", slug:"required") do
render NitroKit::Switch.new(
label:"Security notices",
id:"gallery-switch-required-control",
name:"preferences[security_notices]",
checked:true,
required:true,
html: { id:"gallery-switch-required" }
)
end
sample("Disabled", slug:"disabled") do
render NitroKit::Switch.new(
label:"Legacy synchronization",
description:"Locked while migration is in progress.",
id:"gallery-switch-disabled-control",
name:"preferences[legacy_sync]",
checked:true,
disabled:true,
html: { id:"gallery-switch-disabled" }
)
end
Accessible labels
Descriptions are referenced with aria-describedby instead of becoming part of the accessible name.
Label pressure
Block label
ARIA only
Long description
Create and distribute a replacement production credential before the current credential expires, then revoke the old credential after every deployment target confirms receipt.
sample("Block label", slug:"block") do
render NitroKit::Switch.new(
id:"gallery-switch-block-control",
name:"preferences[activity]",
checked:true,
html: { id:"gallery-switch-block" }
) do
strong { "Activity reports" }
plain(" for workspace owners")
endend
sample("ARIA only", slug:"aria") do
render NitroKit::Switch.new(
id:"gallery-switch-aria-control",
name:"table[compact_rows]",
include_hidden:false,
control_aria: { label:"Use compact table rows" },
html: { id:"gallery-switch-aria" }
)
end
sample("Long description", slug:"long") do
render NitroKit::Switch.new(
label:"Automatic credential rotation",
description:"Create and distribute a replacement production credential before the current credential expires, then revoke the old credential after every deployment target confirms receipt.",
id:"gallery-switch-long-control",
name:"credentials[automatic_rotation]",
html: { id:"gallery-switch-long" }
)
end
Rails form builder
Builder fields map model booleans and validation errors into submittable switch controls.
registration = Registration.new(email:"[email protected]", role:"developer", terms:false)
registration.validate
form_with(
model: registration,
scope::registration,
url:"#registration-switch",
builder:NitroKit::FormBuilder,
id:"gallery-switch-registration-form"
) do |form|
form.group do
form.field(
:terms,
as::switch,
id:"gallery-switch-registration-terms",
label:"Accept workspace terms",
description:"Required before registration is complete.",
required:true
)
form.submit("Continue", id:"gallery-switch-registration-save")
endend
Under pressure
Every hostile identity from Gallery::Hostile as a switch label with sentence and URL descriptions, then a required switch that is also disabled and invalid under a paragraph-length label.
Hostile labels
This description keeps going well past the point where a sensible product would have stopped, because real customers paste release notes, legal disclaimers, and entire support tickets into fields that were designed for a single line of text.
This description keeps going well past the point where a sensible product would have stopped, because real customers paste release notes, legal disclaimers, and entire support tickets into fields that were designed for a single line of text.
This description keeps going well past the point where a sensible product would have stopped, because real customers paste release notes, legal disclaimers, and entire support tickets into fields that were designed for a single line of text.
This description keeps going well past the point where a sensible product would have stopped, because real customers paste release notes, legal disclaimers, and entire support tickets into fields that were designed for a single line of text.
This description keeps going well past the point where a sensible product would have stopped, because real customers paste release notes, legal disclaimers, and entire support tickets into fields that were designed for a single line of text.
must be between 3 and 64 characters, may only contain letters, numbers, hyphens, and underscores, must not start or end with a hyphen, and must not collide with a reserved workspace slug such as admin, api, or www
div[data-nk=switch] containing input[type=checkbox][role=switch]; sizes md lg
Contract
Uses native checkbox submission with an unchecked hidden input by default; checked state stays native, with no Stimulus controller and no mirrored data-state. 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, and is connected with aria-describedby. The ARIA-only form renders the bare control and track without a label wrapper. invalid: true sets aria-invalid on the control. role is owned by Switch: a control_html: { role: ... } value is replaced by role="switch".
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.