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:, inline:, 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

Choose files, then save to process them. The receipt appears here and the uploader clears for the next batch.

Viewport640 px · sm

Width

Preset

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

form_with(
  scope: :upload,
  url: gallery_upload_submissions_path(mode: "direct"),
  builder: NitroKit::FormBuilder,
  id: "gallery-dropzone-direct-form"
) do |form|
  form.group do
    form.dropzone(
      :files,
      id: "gallery-dropzone-direct",
      label: "Upload supporting evidence",
      description: "Text or PNG · 2 files · 2 MB each.",
      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

Files travel with the form request. Processing shows a receipt and clears only this preview.

Viewport640 px · sm

Width

Preset

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

form_with(
  scope: :upload,
  url: gallery_upload_submissions_path(mode: "multipart"),
  builder: NitroKit::FormBuilder,
  id: "gallery-dropzone-multipart-form"
) 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

Both uploads are processed together. Saving clears both inputs and leaves the other examples alone.

Viewport640 px · sm

Width

Preset

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

form_with(
  scope: :upload,
  url: gallery_upload_submissions_path(mode: "shared"),
  builder: NitroKit::FormBuilder,
  id: "gallery-dropzone-shared-form"
) 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
)

Avatar upload

A small photo picker. Choose an image, then save to process it and reset the input.

Viewport640 px · sm

Width

Preset

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

form_with(scope: :upload, url: gallery_upload_submissions_path(mode: "avatar"), builder: NitroKit::FormBuilder) do |form|
  form.group do
    form.dropzone(
      :files,
      id: "gallery-dropzone-avatar",
      presentation: :avatar,
      label: "Change profile photo",
      description: "PNG or JPG, up to 2 MB.",
      accept: "image/png,image/jpeg",
      max_bytes: 2 * 1024 * 1024,
      required: true
    )
    form.submit("Save photo")
  end
end

Table row upload

A tiny attachment control for receipts and dense lists, with a larger touch target on mobile.

Viewport640 px · sm

Width

Preset

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

form_with(scope: :upload, url: gallery_upload_submissions_path(mode: "compact"), builder: NitroKit::FormBuilder) do |form|
  form.group do
    form.dropzone(
      :files,
      id: "gallery-dropzone-compact",
      presentation: :compact,
      label: "Attach receipt",
      description: "PDF, PNG or JPG, up to 2 MB.",
      accept: "application/pdf,image/png,image/jpeg",
      max_bytes: 2 * 1024 * 1024,
      required: true
    )
    form.submit("Save receipt")
  end
end

Inline layout

A compact horizontal drop target with the same file previews and keyboard support.

Upload attachmentsDrop files here or choose them from your device.Drop or choose files.PNG, JPG or PDF, up to 10 MB each.

No files selected.

Viewport640 px · sm

Width

Preset

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

render NitroKit::Dropzone.new(
  id: "gallery-dropzone-inline",
  name: "attachments[files][]",
  label: "Upload attachments",
  description: "PNG, JPG or PDF, up to 10 MB each.",
  inline: true,
  direct_upload: false,
  multiple: true,
  accept: "image/png,image/jpeg,application/pdf",
  max_files: 5,
  max_bytes: 10 * 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

Under pressure

Every presentation labelled and described with Gallery::Hostile's unbroken, mixed-script, and paragraph-length values, under an oversized file policy.

Hostile presentations

Avatar

Dr. Maximiliana Wolfeschlegelsteinhausenbergerdorff-Featherstonehaugh von Hohenzollern-Sigmaringen IIIDrop files here or choose them from your device.Drop or choose files.สวัสดีครับยินดีต้อนรับสู่ระบบจัดการทีมงานของเรา

No files selected.

Viewport640 px · sm

Width

Preset

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

sample("Minimal", slug: "minimal") do
  render NitroKit::Dropzone.new(
    id: "gallery-dropzone-hostile-minimal",
    name: "#{Gallery::Hostile::LONG_SLUG}[files][]",
    label: Gallery::Hostile::LONG_LABEL,
    description: Gallery::Hostile::LONG_PARAGRAPH,
    direct_upload: false,
    multiple: true,
    accept: "image/png,image/jpeg,application/pdf",
    max_files: 999,
    max_bytes: Gallery::Hostile::HUGE_NUMBER
  )
end
sample("Inline", slug: "inline") do
  render NitroKit::Dropzone.new(
    id: "gallery-dropzone-hostile-inline",
    name: "attachments[files][]",
    label: Gallery::Hostile::LONG_WORD,
    description: Gallery::Hostile::LONG_EMAIL,
    inline: true,
    direct_upload: false,
    multiple: true,
    max_files: 999
  )
end
sample("Input", slug: "input") do
  render NitroKit::Dropzone.new(
    id: "gallery-dropzone-hostile-input",
    name: "document[file]",
    label: Gallery::Hostile::CJK_NAME,
    description: Gallery::Hostile::RTL_NAME,
    presentation: :input,
    direct_upload: false
  )
end
sample("Compact", slug: "compact") do
  render NitroKit::Dropzone.new(
    id: "gallery-dropzone-hostile-compact",
    name: "receipt[file]",
    label: Gallery::Hostile::EMOJI_NAME,
    description: Gallery::Hostile::LONG_WORD,
    presentation: :compact,
    direct_upload: false
  )
end
sample("Avatar", slug: "avatar") do
  render NitroKit::Dropzone.new(
    id: "gallery-dropzone-hostile-avatar",
    name: "avatar[file]",
    label: Gallery::Hostile::LONG_NAME,
    description: Gallery::Hostile::THAI_NAME,
    presentation: :avatar,
    direct_upload: false,
    accept: "image/png"
  )
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 avatar compact), inline: false, 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. presentation: :avatar provides an 80px circular image picker with a live photo preview and upload badge; it requires single-file selection and inline: false. presentation: :compact provides a small attachment control for table rows. Both retain labelled native inputs, progress, errors, and removal. inline: true places the upload icon beside the prompt for a compact horizontal target. File rows sit below the drop target, with image thumbnails or decorative file icons, file size, status, progress, and removal. The live summary remains available to assistive technology without repeating the visible list. 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.