The Fluxbit::Form::DropzoneComponent is a drag-and-drop file input component that extends Fluxbit::Form::FieldComponent. It provides a visually rich file upload area that allows users to either drag and drop files or click to select files. The component supports customizable titles, subtitles, icons, different height presets, and integrates seamlessly with Rails form builders.

To start using the dropzone you can use the default way to call the component:

<%= render Fluxbit::Form::DropzoneComponent.new(name: "avatar").with_content('') %>

<!-- or -->

<%= render Fluxbit::Form::DropzoneComponent.new(name: "avatar") do %>
<% end %>

or you can use the alias (from the helpers):

<%= fx_dropzone(name: "avatar") %>

<!-- or -->

<%= fx_dropzone(name: "avatar") do %>
<% end %>

The result is:

Options

Param Default Description
name:   Field name (required unless using a form builder)
label:   Label text above the dropzone
title: true Title text inside dropzone (true for default, false to hide, or custom string)
subtitle: true Subtitle text below title (true for default, false to hide, or custom string)
icon: :upload Icon to display above the title (Anyicon name or symbol)
icon_html: {} Additional HTML attributes for the icon element
height: 0 Height preset (0: auto, 1: h-32, 2: h-64, 3: h-96)
help_text:   Help or error text below the field
helper_popover:   Content for a popover helper
helper_popover_placement: “right” Placement of the popover (:top, :right, :bottom, :left)
multiple: false Allow multiple file selection
accept:   Comma-separated list of accepted file types
disabled: false Disables the input if true
required: false Marks the field as required (adds “required” class to wrapper)
remove_class: ”” Classes to be removed from the default class list
wrapper_html: {} Additional HTML attributes for the wrapper div
**props   Additional HTML attributes for the file input element

Slots

The component supports custom content via the default slot. When content is provided, it replaces the default icon, title, and subtitle:

<%= fx_dropzone(name: "custom_upload") do %>
  <div class="text-center">
    <h3 class="text-lg font-bold">Custom Upload Area</h3>
    <p>Drop your files here</p>
  </div>
<% end %>

Examples

Basic dropzone

Different heights

Custom title and subtitle

Different icons

Multiple file upload

File type restrictions

With helper text

Disabled state

Required vs optional fields

Custom content slot

With form builder

Adding/Removing classes

Adding other properties

When to use

Use Dropzone for:

  • File uploads: Any scenario requiring users to upload files
  • Profile pictures: Avatar or image uploads with visual feedback
  • Document submission: Forms requiring document attachments
  • Multiple file uploads: Batch file processing scenarios
  • Drag-and-drop interfaces: Enhanced UX for file selection
  • Media uploads: Images, videos, or other media content

Internationalization (I18n)

Labels, help texts, and helper popovers can be automatically loaded from translation files. The component will look for translations using Rails’ I18n system based on the form object and attribute names.

Translation Structure 

en:
  model_name:
    fields:
      attribute_name: "Custom Label"
    help_text:
      attribute_name: "Custom help text"
    helper_popover:
      attribute_name: "Custom popover content"

Usage Examples 

# Translation file (config/locales/en.yml)
en:
  product:
    fields:
      image: "Product Image"
      documents: "Supporting Documents"
    help_text:
      image: "Upload a high-quality product image (JPG, PNG, max 5MB)"
      documents: "Upload any supporting documents or manuals"
    helper_popover:
      image: "Choose a clear, well-lit image that showcases your product"

# In your form
<%= fx_dropzone(form: form, attribute: :image) %>
# Automatically uses labels and help text from translations

# Override with custom values
<%= fx_dropzone(form: form, attribute: :image, label: "Custom Label") %>

# Disable automatic labels/help text
<%= fx_dropzone(form: form, attribute: :image, label: false, help_text: false) %>

Override Behavior

  • Custom value: Pass a string to override the translation
  • Disable: Pass false to disable automatic translation lookup
  • Default: Leave blank to use automatic translation lookup

Supported File Operations

  • Single file upload: Default behavior for individual file selection
  • Multiple file upload: Set multiple: true for batch uploads
  • File type filtering: Use accept attribute to restrict file types
  • Drag and drop: Native browser drag-and-drop support
  • Click to browse: Fallback file browser for all devices

Accessibility

  • Uses proper <label> element for file input association
  • File input remains accessible via keyboard navigation
  • Support for disabled state with appropriate visual feedback
  • Screen reader compatible with semantic HTML structure
  • Accepts all standard file input attributes via props
  • ARIA attributes can be added through the props parameter

Customization

You can customize the appearance and behavior of this component by passing different initialization parameters and adding custom styles. To do this you can create a initializer file like the:

# /config/initializers/change_dropzone_component_defaults.rb

Fluxbit::Config::Form::DropzoneComponent.icon = :cloud_upload # the default is :upload
Fluxbit::Config::Form::DropzoneComponent.height = 2 # the default is 0
Fluxbit::Config::Form::DropzoneComponent.styles[:base] = 'w-full border-2 border-dashed border-gray-300 rounded-lg' # modify base styles
Fluxbit::Config::Form::DropzoneComponent.styles[:height][4] = 'h-screen' # add custom height option

Dependencies

Styles 

<%= html_escape(JSON.pretty_generate(Fluxbit::Config::Form::DropzoneComponent.styles)) %>

References

Flowbite File Upload