Dropzone

Native file selection and drag-and-drop with optional Active Storage direct uploads.

Source: app/components/nitro_kit/dropzone.rb
API: NitroKit::Dropzone.new(id:, name:, presentation:, direct_upload:, multiple:, accept:, max_files:, max_bytes:)

Upload modes

Both modes retain a labelled native file input and ordinary multipart form submission.

Active Storage direct upload

Selection starts a direct upload, writes signed blob IDs, and keeps the form unavailable until uploads settle.

Viewport640 px · sm

Width

Preset

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

form_with(
  scope: :upload,
  url: gallery_upload_submissions_path,
  builder: NitroKit::FormBuilder,
  id: "gallery-dropzone-direct-form",
  data: { turbo: false }
) do |form|
  form.group do
    form.dropzone(
      :files,
      id: "gallery-dropzone-direct",
      label: "Upload supporting evidence",
      description: "Up to two text or PNG files, each no larger than 2 MB.",
      multiple: true,
      accept: "text/plain,image/png",
      max_files: 2,
      max_bytes: 2 * 1024 * 1024,
      required: true
    )
    form.submit("Save direct upload", id: "gallery-dropzone-direct-submit")
  end
end

Ordinary multipart upload

With direct upload disabled, dropped and selected files stay on the native input for the normal form request.

Viewport640 px · sm

Width

Preset

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

form_with(
  scope: :upload,
  url: gallery_upload_submissions_path,
  builder: NitroKit::FormBuilder,
  id: "gallery-dropzone-multipart-form",
  data: { turbo: false }
) do |form|
  form.group do
    form.dropzone(
      :files,
      id: "gallery-dropzone-multipart",
      label: "Add source files",
      description: "Choose up to three text or PNG files.",
      direct_upload: false,
      multiple: true,
      accept: "text/plain,image/png",
      max_files: 3,
      max_bytes: 1024 * 1024
    )
    form.submit("Submit files", id: "gallery-dropzone-multipart-submit")
  end
end

Shared form uploads

Each Dropzone keeps the shared form unavailable only while its own upload is active.

Viewport640 px · sm

Width

Preset

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

form_with(
  scope: :upload,
  url: gallery_upload_submissions_path,
  builder: NitroKit::FormBuilder,
  id: "gallery-dropzone-shared-form",
  data: { turbo: false }
) do |form|
  form.group do
    form.dropzone(
      :primary_file,
      id: "gallery-dropzone-shared-primary",
      label: "Upload primary evidence",
      accept: "text/plain"
    )
    form.dropzone(
      :secondary_file,
      id: "gallery-dropzone-shared-secondary",
      label: "Upload secondary evidence",
      accept: "text/plain"
    )
    form.submit("Save both uploads", id: "gallery-dropzone-shared-submit")
    form.button(
      "Unavailable action",
      id: "gallery-dropzone-shared-disabled-submit",
      type: :submit,
      disabled: true
    )
  end
end

Presentation

The default minimal presentation hides the native file input, so the drop target is the only visible affordance. The input presentation keeps the native control visible beside it.

Drop target only

The input stays operable, focusable, and named: its own label opens the file picker, and the drop target wears the focus ring while the input has focus.

Replace the workspace avatarDrop files here or choose them from your device.Drop or choose files.One PNG, no larger than 1 MB.

No files selected.

Viewport640 px · sm

Width

Preset

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

render NitroKit::Dropzone.new(
  id: "gallery-dropzone-minimal",
  name: "avatar[file]",
  label: "Replace the workspace avatar",
  description: "One PNG, no larger than 1 MB.",
  direct_upload: false,
  accept: "image/png",
  max_bytes: 1024 * 1024
)

Visible native input

presentation: :input keeps the native file control visible beside the drop target.

Attach a documentDrop files here or choose them from your device.Drop or choose files.One PDF, no larger than 2 MB.

No files selected.

Viewport640 px · sm

Width

Preset

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

render NitroKit::Dropzone.new(
  id: "gallery-dropzone-native-input",
  name: "attachment[file]",
  label: "Attach a document",
  description: "One PDF, no larger than 2 MB.",
  presentation: :input,
  direct_upload: false,
  accept: "application/pdf",
  max_bytes: 2 * 1024 * 1024
)

Availability and constraints

Required, multiple, disabled, type, count, and byte limits are explicit Ruby options and native attributes.

Constraint states

Viewport640 px · sm

Width

Preset

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

sample("Required single file", slug: "required-single") do
  render NitroKit::Dropzone.new(
    id: "gallery-dropzone-required",
    name: "evidence[file]",
    label: "Choose one PDF",
    description: "The browser keeps this requirement without JavaScript.",
    direct_upload: false,
    accept: "application/pdf",
    max_bytes: 512 * 1024,
    required: true
  )
end

sample("Disabled", slug: "disabled") do
  render NitroKit::Dropzone.new(
    id: "gallery-dropzone-disabled",
    name: "archive[file]",
    label: "Archived upload",
    description: "Uploads are unavailable while this record is archived.",
    disabled: true
  )
end

Component contract

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

docs/component_contracts.md · NitroKit::Dropzone

Constructor-specific options: required id:, name:
label: defaulting to I18n.t("nitro_kit.dropzone.label"), description: nil, presentation: :minimal (minimal input), direct_upload: true, multiple: false, accept: nil, max_files: 1, max_bytes: nil, disabled: false, required: false
Root and closed vocabulary: div[data-nk=dropzone][data-presentation]; states idle drag uploading success error disabled
Contract: Owns a labelled native input, description/error/live status, preview list, native progress, and remove controls. label: is the visible prompt heading and renders in the dropzone-title slot; it replaced the former title: keyword. Every other user-facing string comes from the nitro_kit.dropzone.* locale scope, and CONTROLLER_MESSAGE_KEYS hands the runtime strings to nk--dropzone as Stimulus values so no English lives in JavaScript. Limits are positive and consistent; max_files must be 1 unless multiple: true. Keyboard selection and direct_upload: false preserve ordinary form submission. The default minimal presentation hides the native input visually while keeping it focusable and named, so the drop target is the only visible affordance; presentation: :input keeps the native control visible beside the drop target.

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.