Field group

A layout boundary for related direct or FormBuilder-backed fields.

Source: app/components/nitro_kit/field_group.rb
API: NitroKit::FieldGroup.new { fields } or form.group { fields }

Grouping boundaries

FieldGroup owns layout only; native field meaning remains with its composed children.

Direct groups

One field

Workspace name

Empty

Viewport640 px · sm

Width

Preset

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

sample("One field", slug: "one") do
  render NitroKit::FieldGroup.new(html: { id: "gallery-field-group-one" }) do
    render NitroKit::Field.new(
      nil,
      :workspace_name,
      id: "gallery-field-group-workspace-name",
      name: "workspace[name]",
      value: "Mothership",
      label: "Workspace name",
      required: true
    )
  end
end
sample("Empty", slug: "empty") do
  render NitroKit::FieldGroup.new(html: { id: "gallery-field-group-empty" }) { nil }
end

Mixed controls

Summary

Time zone

Send a weekly digest

Deployment alerts

Notify workspace owners after production deploys.

Viewport640 px · sm

Width

Preset

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

render NitroKit::FieldGroup.new(html: { id: "gallery-field-group-mixed" }) do
  render NitroKit::Field.new(
    nil,
    :summary,
    as: :textarea,
    id: "gallery-field-group-summary",
    name: "workspace[summary]",
    value: "Release planning and production operations.",
    label: "Summary"
  )
  render NitroKit::Field.new(
    nil,
    :time_zone,
    as: :select,
    id: "gallery-field-group-time-zone",
    name: "workspace[time_zone]",
    value: "Europe/Copenhagen",
    label: "Time zone",
    options: Gallery::Forms::Profile::TIME_ZONES
  )
  render NitroKit::Field.new(
    nil,
    :weekly_digest,
    as: :checkbox,
    id: "gallery-field-group-weekly-digest",
    name: "workspace[weekly_digest]",
    label: "Send a weekly digest",
    checked: true
  )
  render NitroKit::Field.new(
    nil,
    :deployment_alerts,
    as: :switch,
    id: "gallery-field-group-deployment-alerts",
    name: "workspace[deployment_alerts]",
    label: "Deployment alerts",
    description: "Notify workspace owners after production deploys."
  )
end

Rails form builder

Builder groups organize related model fields while Rails continues to own names, values, and errors.

Profile sections

Viewport640 px · sm

Width

Preset

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

profile = Gallery::FormExamples.profile(:invalid)

form_with(
  model: profile,
  scope: :profile,
  url: "#profile-groups",
  builder: NitroKit::FormBuilder,
  id: "gallery-field-group-profile-form"
) do |form|
  form.group(html: { id: "gallery-field-group-profile-identity" }) do
    form.field(:name, id: "gallery-field-group-profile-name", required: true)
    form.field(
      :email,
      as: :email,
      id: "gallery-field-group-profile-email",
      description: "Used for account recovery.",
      required: true
    )
  end
  form.group(html: { id: "gallery-field-group-profile-details" }) do
    form.field(
      :bio,
      as: :textarea,
      id: "gallery-field-group-profile-bio",
      description: "Shown to workspace members."
    )
    form.field(
      :time_zone,
      as: :select,
      id: "gallery-field-group-profile-time-zone",
      prompt: "Choose a time zone",
      options: Gallery::Forms::Profile::TIME_ZONES,
      required: true
    )
  end
  form.submit("Save profile", id: "gallery-field-group-profile-save")
end

Long grouped form

Long labels and guidance do not require a different grouping API.

Credential policy

Number of days before expiration when replacement credentials should be generated

A notification is sent first; production credentials are never revoked until every target confirms receipt.

Require owner confirmation before revoking the previous production credential

Viewport640 px · sm

Width

Preset

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

render NitroKit::FieldGroup.new(html: { id: "gallery-field-group-pressure" }) do
  render NitroKit::Field.new(
    nil,
    :rotation_window,
    as: :number,
    id: "gallery-field-group-rotation-window",
    name: "credential_policy[rotation_window]",
    value: 14,
    label: "Number of days before expiration when replacement credentials should be generated",
    description: "A notification is sent first; production credentials are never revoked until every target confirms receipt.",
    min: 1,
    max: 90,
    required: true
  )
  render NitroKit::Field.new(
    nil,
    :confirmation,
    as: :checkbox,
    id: "gallery-field-group-rotation-confirmation",
    name: "credential_policy[confirmation]",
    label: "Require owner confirmation before revoking the previous production credential",
    checked: true
  )
end

Component contract

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

docs/component_contracts.md · NitroKit::FieldGroup

Constructor-specific options: no component-specific keywords
Root and closed vocabulary: div[data-nk=field-group]
Contract: Requires a content block. It is the default vertical rhythm boundary for a standalone form's visible fields, submit control, and related links. A sibling immediately following the group receives the group gap as margin-block-start.

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.