Form section

A section frame for one complete caller-owned Rails form and an optional typed status.

Source: The complete form element is a named leaf. Rails keeps naming, CSRF, model errors, multipart behavior, and submission semantics.
API: Supply the required title and optional description through constructor text or matching compound methods. form requires exactly one block that renders a complete form. status accepts at most one NitroKit::Alert before it.

Rails-owned complete forms

The section frames one complete form and an optional typed status without owning fields, models, routes, or submission policy.

Minimal form

Workspace name

Viewport640 px · sm

Width

Preset

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

render_settings_section(
  id: "gallery-settings-section-minimal",
  title: "Workspace name",
  fields: [ [ :name, "Workspace name" ] ]
)

Validation status

Profile

Public details shown to workspace members.

Profile was not saved

Correct the highlighted name and email fields.

Viewport640 px · sm

Width

Preset

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

render NitroKit::SettingsSection.new(
  title: "Profile",
  description: "Public details shown to workspace members.",
  id: "gallery-settings-section-validation"
) do |section|
  section.status NitroKit::Alert.new(variant: :destructive, id: "gallery-settings-section-validation-status") do |alert|
    alert.title("Profile was not saved")
    alert.description("Correct the highlighted name and email fields.")
  end
  section.form do
    form_with(url: "#profile", scope: :profile, builder: NitroKit::FormBuilder, id: "gallery-settings-section-validation-form") do |form|
      form.group do
        form.field(:name, label: "Display name", value: "", errors: [ "Display name can't be blank" ], required: true)
        form.field(:email, as: :email, label: "Email", value: "not-an-email", errors: [ "Email is invalid" ], required: true)
        form.submit("Save profile")
      end
    end
  end
end

Success status

Notification settings

Choose which operational changes should send email.

Notification settings saved

New incidents and weekly summaries will be delivered to [email protected].

Viewport640 px · sm

Width

Preset

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

render NitroKit::SettingsSection.new(
  title: "Notification settings",
  description: "Choose which operational changes should send email.",
  id: "gallery-settings-section-success"
) do |section|
  section.status NitroKit::Alert.new(variant: :success, id: "gallery-settings-section-success-status") do |alert|
    alert.title("Notification settings saved")
    alert.description("New incidents and weekly summaries will be delivered to [email protected].")
  end
  section.form do
    form_with(url: "#notifications", scope: :notifications, builder: NitroKit::FormBuilder, id: "gallery-settings-section-success-form") do |form|
      form.group do
        form.field(:incidents, as: :switch, label: "Incident alerts", checked: true)
        form.field(:summaries, as: :switch, label: "Weekly summaries", checked: true)
        form.submit("Save notifications")
      end
    end
  end
end

Dense long form

International Research and Reliability workspace profile

Long labels, guidance, and a complete caller-owned form exercise the boundary without teaching the section about a Rails model.

ViewportFull width

Width

Preset

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

render NitroKit::Container.new(size: :lg, id: "gallery-settings-section-dense-container") do
  render_settings_section(
    id: "gallery-settings-section-dense",
    title: "International Research and Reliability workspace profile",
    description: "Long labels, guidance, and a complete caller-owned form exercise the boundary without teaching the section about a Rails model.",
    fields: [
      [ :name, "Official workspace name" ],
      [ :billing_email, "Billing and compliance contact email" ],
      [ :legal_entity, "Contracting legal entity" ],
      [ :data_region, "Primary encrypted data residency region" ],
      [ :retention, "Audit event retention policy acknowledgement" ]
    ]
  )
end

Under pressure

An unbroken hundred-letter title, four paragraphs of description, a destructive status carrying the full slug error, and a form whose labels, values, help text, and errors all come from Gallery::Hostile.

Hostile form

Wolfeschlegelsteinhausenbergerdorffwelchevoralternwarengewissenhaftschaferswessenschafewarenwohlgepflege

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.

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

Workspace slug 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.

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

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

Billing email

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

🦄 Unicorn Ops 🚀🔥💯 On-call

สวัสดีครับยินดีต้อนรับสู่ระบบจัดการทีมงานของเรา

ViewportFull width

Width

Preset

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

render NitroKit::SettingsSection.new(
  title: Gallery::Hostile::LONG_WORD,
  description: Gallery::Hostile::LONG_PARAGRAPH,
  id: "gallery-settings-section-hostile"
) do |section|
  section.status NitroKit::Alert.new(variant: :destructive, id: "gallery-settings-section-hostile-status") do |alert|
    alert.title(Gallery::Hostile::LONG_LABEL)
    alert.description("Workspace slug #{Gallery::Hostile::LONG_ERROR}.")
  end
  section.form do
    form_with(url: "#hostile", scope: :workspace, builder: NitroKit::FormBuilder, id: "gallery-settings-section-hostile-form") do |form|
      form.group do
        form.field(
          :slug,
          id: "gallery-settings-section-hostile-slug",
          label: Gallery::Hostile::LONG_LABEL,
          value: Gallery::Hostile::LONG_WORD,
          errors: [ Gallery::Hostile::LONG_ERROR ],
          required: true
        )
        form.field(
          :billing_email,
          as: :email,
          id: "gallery-settings-section-hostile-email",
          label: "Billing email",
          value: Gallery::Hostile::LONG_EMAIL,
          description: Gallery::Hostile::LONG_SENTENCE
        )
        form.field(
          :owner,
          id: "gallery-settings-section-hostile-owner",
          label: Gallery::Hostile::RTL_NAME,
          value: Gallery::Hostile::CJK_NAME
        )
        form.field(
          :webhook_url,
          as: :url,
          id: "gallery-settings-section-hostile-webhook",
          label: Gallery::Hostile::EMOJI_NAME,
          value: Gallery::Hostile::LONG_URL
        )
        form.field(
          :notes,
          as: :textarea,
          id: "gallery-settings-section-hostile-notes",
          label: Gallery::Hostile::THAI_NAME,
          value: Gallery::Hostile::LONG_PARAGRAPH
        )
        form.submit(Gallery::Hostile::ACTION_LABELS.fetch(1), id: "gallery-settings-section-hostile-submit")
      end
    end
  end
end

Component contract

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

docs/component_contracts.md · NitroKit::SettingsSection

Constructor: title: nil, description: nil, level: 2, id: nil
Root: section[data-nk=settings-section][aria-labelledby] naming the title heading; title levels 1..6
Compound contract: Requires title; title and description each accept constructor text or one matching text/rich-content compound declaration, and title also accepts level:. Exactly one form block; at most one Alert through status.

Relevant patterns

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

docs/patterns/resource_form.md · docs/patterns/crud_resource.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.

Complete product resource

Define the resource, tenant boundary, actor, lifecycle, visibility, and states before writing views.
Build index, form, detail, destructive action, and tests as one product surface.
Use one shell toolbar title and one application-owned page gutter; do not repeat hierarchy across nested components.
Scope every lookup through the current tenant and model meaningful lifecycle transitions as noun resources.

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.