Field

Labels, descriptions, controls, and validation errors as one accessible unit.

Source: app/components/nitro_kit/field.rb
API: NitroKit::Field.new(form, name, label:, description:, errors:)

Control modes

One field contract composes labels and descriptions around native control types.

Text controls

Text

Workspace name

Visible to everyone in the workspace.

Textarea

Biography

ViewportFull width

Width

Preset

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

sample("Text", slug: "text") do
  render NitroKit::Field.new(
    nil,
    :workspace_name,
    id: "gallery-field-text",
    value: "Mothership",
    label: "Workspace name",
    description: "Visible to everyone in the workspace.",
    required: true,
    html: { id: "gallery-field-text-wrapper" }
  )
end
sample("Textarea", slug: "textarea") do
  render NitroKit::Field.new(
    nil,
    :bio,
    as: :textarea,
    id: "gallery-field-textarea",
    value: "Building reliable interfaces for analytical software.",
    label: "Biography",
    html: { id: "gallery-field-textarea-wrapper" }
  )
end

Choice controls

Select

Time zone

Radio group

Default member role

Administrator

Member

Viewer

ViewportFull width

Width

Preset

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

sample("Select", slug: "select") do
  render NitroKit::Field.new(
    nil,
    :time_zone,
    as: :select,
    id: "gallery-field-select",
    value: "Europe/Copenhagen",
    label: "Time zone",
    prompt: "Choose a time zone",
    options: Gallery::Forms::Profile::TIME_ZONES,
    html: { id: "gallery-field-select-wrapper" }
  )
end
sample("Radio group", slug: "radio-group") do
  render NitroKit::Field.new(
    nil,
    :role,
    as: :radio_group,
    id: "gallery-field-radio-group",
    value: "member",
    label: "Default member role",
    options: [ [ "Administrator", "admin" ], [ "Member", "member" ], [ "Viewer", "viewer" ] ],
    html: { id: "gallery-field-radio-group-wrapper" }
  )
end

Boolean controls

Checkbox

Send a weekly digest

Includes deployments, invitations, and billing events.

Switch

Deployment alerts

Notify the operations channel after every production deploy.

ViewportFull width

Width

Preset

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

sample("Checkbox", slug: "checkbox") do
  render NitroKit::Field.new(
    nil,
    :weekly_digest,
    as: :checkbox,
    id: "gallery-field-checkbox",
    checked: true,
    label: "Send a weekly digest",
    description: "Includes deployments, invitations, and billing events.",
    html: { id: "gallery-field-checkbox-wrapper" }
  )
end
sample("Switch", slug: "switch") do
  render NitroKit::Field.new(
    nil,
    :deployment_alerts,
    as: :switch,
    id: "gallery-field-switch",
    checked: true,
    label: "Deployment alerts",
    description: "Notify the operations channel after every production deploy.",
    html: { id: "gallery-field-switch-wrapper" }
  )
end

States

Required, disabled, and invalid state is visible on the field and connected control.

Availability and validation

Required

Account email

Disabled

Legacy account ID

Invalid

Account email

Used for security notices and account recovery.

Email is invalid

Viewport640 px · sm

Width

Preset

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

sample("Required", slug: "required") do
  render NitroKit::Field.new(
    nil,
    :email,
    as: :email,
    id: "gallery-field-required",
    value: "[email protected]",
    label: "Account email",
    required: true,
    html: { id: "gallery-field-required-wrapper" }
  )
end
sample("Disabled", slug: "disabled") do
  render NitroKit::Field.new(
    nil,
    :legacy_id,
    id: "gallery-field-disabled",
    value: "acct_legacy_42",
    label: "Legacy account ID",
    disabled: true,
    html: { id: "gallery-field-disabled-wrapper" }
  )
end
sample("Invalid", slug: "invalid") do
  invalid_profile = Gallery::FormExamples.profile(:invalid)
  render NitroKit::Field.new(
    nil,
    :email,
    as: :email,
    id: "gallery-field-invalid",
    value: invalid_profile.email,
    label: "Account email",
    description: "Used for security notices and account recovery.",
    errors: invalid_profile.errors.full_messages_for(:email),
    required: true,
    html: { id: "gallery-field-invalid-wrapper" }
  )
end

Placement parents

A Field owns its label, description, error, and one control, and nothing outside itself. Everything between fields belongs to a parent. FieldGroup — `form.group` on the builder — is the default vertical rhythm owner for bare fields and actions; two bare siblings stack flush. Fieldset provides that rhythm for its direct field, group, and submit children while adding native grouping: reach for it when a set of fields needs one shared accessible name, and take the legend and description it brings with it. SettingsSection is also optional and is the page-level region above the form: a titled header, an optional status Alert, and exactly one form. Flex and Grid own placement when an arrangement is deliberately inline or multi-column.

Section, fieldset, and group together

The section titles the region, the fieldset names the related address fields, and each FieldGroup owns the gap between the controls it contains.

Billing contact

Invoices and receipts are sent to this contact.

ViewportFull width

Width

Preset

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

render NitroKit::SettingsSection.new(
  title: "Billing contact",
  description: "Invoices and receipts are sent to this contact.",
  id: "gallery-field-placement-section"
) do |section|
  section.form do
    billing = Gallery::FormExamples.billing_contact

    form_with(
      model: billing,
      scope: :billing_contact,
      url: "#billing-contact",
      builder: NitroKit::FormBuilder,
      id: "gallery-field-placement-form"
    ) do |form|
      form.group do
        form.field(:company_name, id: "gallery-field-placement-company", label: "Company name", required: true)
        form.field(:billing_email, as: :email, id: "gallery-field-placement-email", label: "Billing email")
      end

      render NitroKit::Fieldset.new(
        legend: "Tax registration",
        description: "Required for workspaces billed inside the EU.",
        html: { id: "gallery-field-placement-fieldset" }
      ) do
        form.group do
          form.field(
            :country,
            as: :select,
            id: "gallery-field-placement-country",
            label: "Country",
            options: [ [ "Denmark", "DK" ], [ "Germany", "DE" ], [ "United States", "US" ] ]
          )
          form.field(:tax_id, id: "gallery-field-placement-tax-id", label: "Tax ID")
        end
      end

      form.submit("Save billing contact", id: "gallery-field-placement-save")
    end
  end
end

Long content

Customer-provided labels and detailed guidance wrap without changing the component API.

Detailed configuration

Production workspace webhook destination

Nitro Kit sends deployment, access, and billing events to this HTTPS endpoint. Changing it affects every administrator in the workspace.

Viewport640 px · sm

Width

Preset

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

render NitroKit::Field.new(
  nil,
  :webhook_url,
  as: :url,
  id: "gallery-field-long-content",
  value: "https://integrations.example.test/nitro/events/production-workspace",
  label: "Production workspace webhook destination",
  description: "Nitro Kit sends deployment, access, and billing events to this HTTPS endpoint. " \
    "Changing it affects every administrator in the workspace.",
  required: true,
  html: { id: "gallery-field-long-content-wrapper" }
)

Under pressure

Hostile labels, paragraph-length guidance, overlong errors, and unbroken values from Gallery::Hostile on text and choice controls, including required fields that are also disabled and invalid.

Hostile text fields

Regional data residency, retention, and lawful-basis preferences for every workspace

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

Wolfeschlegelsteinhausenbergerdorffwelchevoralternwarengewissenhaftschaferswessenschafewarenwohlgepflege

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

محمد عبد الرحمن الهاشمي القحطاني

山田太郎（プラットフォームエンジニアリング）

🦄 Unicorn Ops 🚀🔥💯 On-call

https://enterprise-holdings-international.example/workspaces/analytical-engines-research-and-production/settings/integrations/webhooks/deliveries/whd_01J8ZK3Q9W7RX2M5N6P8T4V1Y0/attempts/3?include=headers,body,response&expand=endpoint.owner

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
Wolfeschlegelsteinhausenbergerdorffwelchevoralternwarengewissenhaftschaferswessenschafewarenwohlgepflege

Viewport640 px · sm

Width

Preset

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

render NitroKit::FieldGroup.new(html: { id: "gallery-field-hostile-text-group" }) do
  render NitroKit::Field.new(
    nil,
    :email,
    as: :email,
    id: "gallery-field-hostile-email",
    name: "hostile[email]",
    value: Gallery::Hostile::LONG_EMAIL,
    label: Gallery::Hostile::LONG_LABEL,
    description: Gallery::Hostile::LONG_PARAGRAPH,
    errors: [ Gallery::Hostile::LONG_ERROR ],
    required: true,
    html: { id: "gallery-field-hostile-email-wrapper" }
  )
  render NitroKit::Field.new(
    nil,
    :slug,
    id: "gallery-field-hostile-locked",
    name: "hostile[slug]",
    value: Gallery::Hostile::LONG_WORD,
    label: Gallery::Hostile::LONG_WORD,
    description: Gallery::Hostile::LONG_SENTENCE,
    errors: [ Gallery::Hostile::LONG_ERROR ],
    required: true,
    disabled: true,
    html: { id: "gallery-field-hostile-locked-wrapper" }
  )
  render NitroKit::Field.new(
    nil,
    :webhook,
    as: :url,
    id: "gallery-field-hostile-url",
    name: "hostile[webhook]",
    value: Gallery::Hostile::LONG_URL,
    label: Gallery::Hostile::RTL_NAME,
    description: Gallery::Hostile::CJK_NAME,
    html: { id: "gallery-field-hostile-url-wrapper" }
  )
  render NitroKit::Field.new(
    nil,
    :notes,
    as: :textarea,
    id: "gallery-field-hostile-textarea",
    name: "hostile[notes]",
    value: Gallery::Hostile::LONG_PARAGRAPH,
    label: Gallery::Hostile::EMOJI_NAME,
    description: Gallery::Hostile::LONG_URL,
    errors: [ Gallery::Hostile::LONG_ERROR, Gallery::Hostile::LONG_WORD ],
    rows: 3,
    html: { id: "gallery-field-hostile-textarea-wrapper" }
  )
end

Hostile choice fields

Viewport640 px · sm

Width

Preset

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

options = Gallery::Hostile::CHOICES

render NitroKit::FieldGroup.new(html: { id: "gallery-field-hostile-choice-group" }) do
  render NitroKit::Field.new(
    nil,
    :status,
    as: :select,
    id: "gallery-field-hostile-select",
    name: "hostile[status]",
    value: "hostile_3",
    label: Gallery::Hostile::LONG_LABEL,
    description: Gallery::Hostile::LONG_SENTENCE,
    errors: [ Gallery::Hostile::LONG_ERROR ],
    options:,
    required: true,
    html: { id: "gallery-field-hostile-select-wrapper" }
  )
  render NitroKit::Field.new(
    nil,
    :role,
    as: :radio_group,
    id: "gallery-field-hostile-radio-group",
    name: "hostile[role]",
    value: "hostile_1",
    label: Gallery::Hostile::LONG_WORD,
    description: Gallery::Hostile::LONG_PARAGRAPH,
    errors: [ Gallery::Hostile::LONG_ERROR ],
    options:,
    required: true,
    html: { id: "gallery-field-hostile-radio-group-wrapper" }
  )
  render NitroKit::Field.new(
    nil,
    :agreement,
    as: :checkbox,
    id: "gallery-field-hostile-checkbox",
    name: "hostile[agreement]",
    label: Gallery::Hostile::LONG_LABEL,
    description: Gallery::Hostile::LONG_PARAGRAPH,
    errors: [ Gallery::Hostile::LONG_ERROR ],
    required: true,
    disabled: true,
    html: { id: "gallery-field-hostile-checkbox-wrapper" }
  )
  render NitroKit::Field.new(
    nil,
    :alerts,
    as: :switch,
    id: "gallery-field-hostile-switch",
    name: "hostile[alerts]",
    checked: true,
    label: Gallery::Hostile::LONG_WORD,
    description: Gallery::Hostile::THAI_NAME,
    html: { id: "gallery-field-hostile-switch-wrapper" }
  )
end

Component contract

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

docs/component_contracts.md · NitroKit::Field

Constructor-specific options: optional Rails form builder and field name
see the full signature below
Root and closed vocabulary: div[data-nk=field][data-field-type=…]; types listed below
Contract: Default rendering owns label, description, control, and errors. A render block replaces the default composition. label, description, control, and errors remain available to custom compositions. The error list keeps native list semantics and uses aria-live=assertive; controls reference it through aria-describedby. Derived labels use human_attribute_name when the form object supplies one. as: :radio_group requires a legend and rejects label: false, falling back to I18n.t("nitro_kit.field.options_legend") when neither an explicit nor a derived label exists. as: :combobox binds the field label to #{id}-input through for and aria-labelledby and wires description, error, and invalid state onto the combobox input.

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.