Skip to content
Nitro Kitv2.0.0.alpha.4

Search gallery…

IntroductionGalleryAgent guideGalleryHuman guideGalleryColorsFoundations · ThemeTypographyFoundations · ThemeSpacing & sizingFoundations · ThemeEffectsFoundations · ThemeButtonComponents · ActionsButton groupComponents · ActionsButton toComponents · ActionsAppearance pickerComponents · FormsCheckboxComponents · FormsCheckbox groupComponents · FormsComboboxComponents · FormsControl groupComponents · FormsDropzoneComponents · FormsFieldComponents · FormsField groupComponents · FormsFieldsetComponents · FormsInputComponents · FormsLabelComponents · FormsRadio buttonComponents · FormsRadio button groupComponents · FormsRich text areaComponents · FormsSelectComponents · FormsSwitchComponents · FormsTextareaComponents · FormsCommand paletteComponents · OverlaysDialogComponents · OverlaysDropdownComponents · OverlaysSheetComponents · OverlaysTooltipComponents · OverlaysAlertComponents · FeedbackEmpty stateComponents · FeedbackToastComponents · FeedbackAccordionComponents · Data displayAvatarComponents · Data displayAvatar stackComponents · Data displayBadgeComponents · Data displayDetails tableComponents · Data displayIconComponents · Data displayProgressive imageComponents · Data displayStat gridComponents · Data displayTableComponents · Data displayTypesetComponents · Data displayPaginationComponents · NavigationPagination barComponents · NavigationTabsComponents · NavigationToolbarComponents · NavigationCardComponents · LayoutContainerComponents · LayoutFlexComponents · LayoutGridComponents · LayoutApplication navigationComponents · ApplicationApplication shellComponents · ApplicationAuthentication shellComponents · ApplicationDanger zoneComponents · ApplicationData sectionComponents · ApplicationForm sectionComponents · ApplicationPage headerComponents · ApplicationSettings layoutComponents · ApplicationSign inCompositions · Access & onboardingPassword resetCompositions · Access & onboardingEmail verificationCompositions · Access & onboardingInvitation acceptanceCompositions · Access & onboardingAccount creationCompositions · Access & onboardingAccount securityCompositions · Access & onboardingWorkspace onboardingCompositions · Access & onboardingBranched onboardingCompositions · Access & onboardingWorkspace dashboardCompositions · Workspace & organizationWorkspace settingsCompositions · Workspace & organizationWorkspace usersCompositions · Workspace & organizationTeam managementCompositions · Workspace & organizationAPI credentialsCompositions · Workspace & organizationOrganization overviewCompositions · Workspace & organizationOrganization settingsCompositions · Workspace & organizationTeam activityCompositions · Workspace & organizationTeam memberCompositions · Workspace & organizationSubscription billingCompositions · Billing & commerceCheckout and paymentCompositions · Billing & commerceCheckout resultsCompositions · Billing & commerceData resource overviewCompositions · Data & operationsData resource activityCompositions · Data & operationsData resource settingsCompositions · Data & operationsProduct resource lifecycleCompositions · Data & operationsAPI webhooksCompositions · Data & operationsIntegration managementCompositions · Data & operationsFile uploadsCompositions · Data & operationsActivity and audit logCompositions · Data & operationsChangelogCompositions · Product & supportHelp centerCompositions · Product & supportSystem status and errorsCompositions · Product & supportProduct landingCompositions · MarketingPublic pricingCompositions · MarketingProduct featuresCompositions · MarketingPublic contactCompositions · MarketingSidebar operations applicationCompositions · Complete applicationsTopbar media applicationCompositions · Complete applicationsHybrid account applicationCompositions · Complete applications

No destinations found.

  • Introduction
  • Agent guide
  • Human guide
  • Foundations
    • Colors
    • Typography
    • Spacing & sizing
    • Effects
  • Actions
    • Button
    • Button group
    • Button to
  • Forms
    • Appearance picker
    • Checkbox
    • Checkbox group
    • Combobox
    • Control group
    • Dropzone
    • Field
    • Field group
    • Fieldset
    • Input
    • Label
    • Radio button
    • Radio button group
    • Rich text area
    • Select
    • Switch
    • Textarea
  • Overlays
    • Command palette
    • Dialog
    • Dropdown
    • Sheet
    • Tooltip
  • Feedback
    • Alert
    • Empty state
    • Toast
  • Data display
    • Accordion
    • Avatar
    • Avatar stack
    • Badge
    • Details table
    • Icon
    • Progressive image
    • Stat grid
    • Table
    • Typeset
  • Navigation
    • Pagination
    • Pagination bar
    • Tabs
    • Toolbar
  • Layout
    • Card
    • Container
    • Flex
    • Grid
  • Application
    • Application navigation
    • Application shell
    • Authentication shell
    • Danger zone
    • Data section
    • Form section
    • Page header
    • Settings layout
  • Access & onboarding
    • Sign in
    • Password reset
    • Email verification
    • Invitation acceptance
    • Account creation
    • Account security
    • Workspace onboarding
    • Branched onboarding
  • Workspace & organization
    • Workspace dashboard
    • Workspace settings
    • Workspace users
    • Team management
    • API credentials
    • Organization overview
    • Organization settings
    • Team activity
    • Team member
  • Billing & commerce
    • Subscription billing
    • Checkout and payment
    • Checkout results
  • Data & operations
    • Data resource overview
    • Data resource activity
    • Data resource settings
    • Product resource lifecycle
    • API webhooks
    • Integration management
    • File uploads
    • Activity and audit log
  • Product & support
    • Changelog
    • Help center
    • System status and errors
  • Marketing
    • Product landing
    • Public pricing
    • Product features
    • Public contact
  • Complete applications
    • Sidebar operations application
    • Topbar media application
    • Hybrid account application

Dialog

A native dialog with Nitro-owned trigger, state, and accessible relationships.

Source
app/components/nitro_kit/dialog.rb
API
NitroKit::Dialog.new(id:) { |dialog| dialog.trigger; dialog.panel }

Action cluster

The Dialog root belongs inside the action layout that places its trigger.

Narrow transcript actions

A converted Redact and Permalink Flex once ended before the Dialog sibling, wrapping its trigger. One no-wrap cluster now owns all three actions, including the Dialog root.

Permalink

Transcript details

The panel block is the yielded application-content slot.

ViewportFull width
Rubytest/dummy/app/components/gallery/components/dialog_page.rb
render NitroKit::Flex.new(
  dir: :row,
  gap: 1,
  align: :center,
  wrap: :nowrap,
  id: "gallery-dialog-transcript-actions"
) do
  render NitroKit::Button.new("Redact", size: :sm, variant: :destructive)
  render NitroKit::Button.new("Permalink", href: "#transcript-permalink", size: :sm)
  render NitroKit::Dialog.new(id: "gallery-dialog-transcript-details") do |dialog|
    dialog.trigger("Details", size: :sm)
    dialog.panel(title: "Transcript details") do
      p { "The panel block is the yielded application-content slot." }
    end
  end
end

Confirmation sequence

The trigger opens a native dialog whose title and description are connected by ID.

Remove team member

Remove Katherine Johnson?

Katherine will immediately lose access to this workspace.
Viewport640 px · sm
Rubytest/dummy/app/components/gallery/components/dialog_page.rb
render NitroKit::Dialog.new(id: "gallery-dialog-remove-member") do |dialog|
  dialog.trigger("Remove member", variant: :destructive)
  dialog.panel(
    title: "Remove Katherine Johnson?",
    description: "Katherine will immediately lose access to this workspace."
  ) do
    dialog.close_button(label: "Keep team member")
    form(
      action: "/gallery/destructive_action",
      method: "post",
      id: "gallery-dialog-delete-form"
    ) do
      input(type: "hidden", name: "_method", value: "delete")
      render NitroKit::Button.new(
        "Remove team member",
        type: :submit,
        variant: :destructive
      )
    end
  end
end

Panel states

Declarative commands open modal dialogs; nonmodal is explicit for server-rendered open panels.

Nonmodal and unavailable

Open nonmodal panel

Release notes

This server-rendered panel is deliberately nonmodal and stays open; dismissal would belong to a page action.
Required decision

Accept the updated terms

This workspace cannot be used until an owner accepts the new processing terms.
Disabled trigger

Unavailable action

Viewport640 px · sm
Rubytest/dummy/app/components/gallery/components/dialog_page.rb
sample("Open nonmodal panel", slug: "nonmodal") do
  render NitroKit::Dialog.new(id: "gallery-dialog-open", dismissible: false) do |dialog|
    dialog.panel(
      title: "Release notes",
      description: "This server-rendered panel is deliberately nonmodal and stays open; dismissal would belong to a page action.",
      nonmodal: true
    )
  end
end
sample("Required decision", slug: "required-decision") do
  render NitroKit::Dialog.new(
    id: "gallery-dialog-required",
    dismissible: false
  ) do |dialog|
    dialog.trigger("Accept updated terms")
    dialog.panel(
      title: "Accept the updated terms",
      description: "This workspace cannot be used until an owner accepts the new processing terms."
    ) do
      render NitroKit::Button.new(
        "Accept terms",
        id: "gallery-dialog-required-accept",
        variant: :primary,
        html: { command: "close", commandfor: "gallery-dialog-required-panel" }
      )
    end
  end
end
sample("Disabled trigger", slug: "disabled-trigger") do
  render NitroKit::Dialog.new(id: "gallery-dialog-disabled") do |dialog|
    dialog.trigger("Unavailable action", disabled: true)
    dialog.panel(title: "Unavailable action") do
      dialog.close_button
    end
  end
end

Long content

The panel scrolls while the close control stays pinned to the top of the panel.

Processing terms

Data processing terms

Review the complete terms before accepting them for this workspace.

Section 1. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 2. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 3. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 4. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 5. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 6. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 7. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 8. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 9. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 10. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 11. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Section 12. The processor handles workspace content only on documented instructions from the controller, keeps every sub-processor under equivalent obligations, and reports a personal-data breach without undue delay.

Viewport640 px · sm
Rubytest/dummy/app/components/gallery/components/dialog_page.rb
render NitroKit::Dialog.new(id: "gallery-dialog-long") do |dialog|
  dialog.trigger("Read processing terms")
  dialog.panel(
    title: "Data processing terms",
    description: "Review the complete terms before accepting them for this workspace."
  ) do
    12.times do |index|
      p do
        "Section #{index + 1}. The processor handles workspace content only on documented " \
          "instructions from the controller, keeps every sub-processor under equivalent " \
          "obligations, and reports a personal-data breach without undue delay."
      end
    end
    dialog.close_button(label: "Close terms")
  end
end

Form composition

Field, Input, and Button compose directly inside a dialog without a second template API.

Invite a teammate

Invite a teammate

Choose an address and the role this person should receive.
Viewport640 px · sm
Rubytest/dummy/app/components/gallery/components/dialog_page.rb
render NitroKit::Dialog.new(id: "gallery-dialog-invite") do |dialog|
  dialog.trigger("Invite teammate", variant: :primary)
  dialog.panel(
    title: "Invite a teammate",
    description: "Choose an address and the role this person should receive."
  ) do
    form(id: "gallery-dialog-invite-form", action: "#invite", method: "post") do
      render NitroKit::FieldGroup.new do
        render NitroKit::Field.new(
          nil,
          :email,
          as: :email,
          id: "gallery-dialog-invite-email",
          name: "invitation[email]",
          value: "[email protected]",
          label: "Email",
          autocomplete: "email",
          required: true,
          html: { id: "gallery-dialog-invite-email-field" }
        )
        render NitroKit::Field.new(
          nil,
          :role,
          as: :select,
          id: "gallery-dialog-invite-role",
          name: "invitation[role]",
          value: "member",
          label: "Role",
          options: Gallery::Forms::TeamInvitation::ROLES,
          html: { id: "gallery-dialog-invite-role-field" }
        )
        render NitroKit::Button.new(
          "Send invitation",
          id: "gallery-dialog-invite-submit",
          type: :submit,
          variant: :primary
        )
      end
      dialog.close_button(label: "Cancel invitation")
    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::Dialog

Constructor-specific options
  • required id:
  • dismissible: true
Root and closed vocabulary
div[data-nk=dialog] owning exactly one native dialog
Compound contract
Requires a declaration block with exactly one panel(title:, description: nil, nonmodal: false) and at most one trigger, which forwards Button treatment options including icon:, icon_end:, and label:, matching Sheet and Dropdown. Nitro renders trigger then panel, and inside the panel it owns close button, title, description, then the captured application content, so a sticky close control survives long scrolling content. At most one close_button(label:) may be declared inside the panel block, whose label defaults to I18n.t("nitro_kit.dialog.close"); dismissible: false renders none and declaring one raises. nonmodal: true is the explicit server-open state and cannot be combined with a trigger, whose command="show-modal" would open the same panel modally. Trigger and close controls use native command/commandfor. Turbo confirmations are deliberately not a Dialog runtime: applications own inline confirmation dialogs, see destructive action (docs/patterns/destructive_action.md).

Relevant patterns

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

docs/patterns/destructive_action.md

Destructive action

  • Use NitroKit::Dialog when the user must review impact or type confirmation; use Turbo's native browser confirmation for a one-sentence consequence.
  • A real Rails form owns the request, and the server owns authorization.
  • Put permanent deletion on the edit route, not the operational show route.
  • Use a server-rendered review route when confirmation must work without JavaScript or Invoker Commands.

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.