Admin Form Builder API

Spree provides a custom Spree::Admin::FormBuilder that extends Rails' standard FormBuilder with additional helper methods designed specifically for the admin interface. This form builder ensures consistent styling, error handling, and behavior across all admin forms.

Using the FormBuilder

The FormBuilder is automatically available in admin forms when using form_with:

<%= form_with model: [:admin, @product] do |f| %>
  <%= f.spree_text_field :name %>
  <%= f.spree_text_area :description %>
<% end %>

Common Options

All FormBuilder methods support these common options:

Text Input Methods

spree_text_field

Creates a text input field with Spree styling.

<%= f.spree_text_field :name %>
<%= f.spree_text_field :sku, required: true %>
<%= f.spree_text_field :code, help: "Leave blank to auto-generate" %>
<%= f.spree_text_field :slug, help_bubble: "URL-friendly identifier" %>

Options:

• All standard Rails text_field options
• All common FormBuilder options

spree_number_field

Creates a number input field with Spree styling.

<%= f.spree_number_field :price, required: true, step: 0.01 %>
<%= f.spree_number_field :quantity, min: 0 %>

Options:

• All standard Rails number_field options (:min, :max, :step)
• All common FormBuilder options

spree_money_field

Creates a locale-aware money/currency input field with automatic formatting. This field displays amounts in the currency's locale format (e.g., 1.234,56 for EUR, 1,234.56 for USD) and normalizes values to standard decimal format before form submission.

<%= f.spree_money_field :amount, currency: 'USD' %>
<%= f.spree_money_field :price, currency: 'EUR', required: true %>
<%= f.spree_money_field :compare_at_amount, currency: @product.currency, label: false %>

Options:

All common FormBuilder options (:label, :required, :help, :help_bubble) are also supported.

Features:

• Locale-aware display: Values are displayed using the currency's decimal mark (e.g., comma for EUR/PLN, dot for USD)
• Automatic normalization: Values are converted to standard decimal format (with . as decimal separator) before form submission
• Currency symbol: Automatically appends the currency symbol when :currency option is provided
• Mobile-friendly: Uses inputmode="decimal" for appropriate mobile keyboard
• Auto-formatting: Values are reformatted on blur to ensure consistent display

Example with nested form:

<%= f.fields_for :prices do |price_form| %>
  <%= price_form.spree_money_field :amount,
                                   currency: price_form.object.currency,
                                   disabled: !can?(:manage, price_form.object),
                                   label: false %>
<% end %>

spree_email_field

Creates an email input field with Spree styling and HTML5 validation.

<%= f.spree_email_field :email, required: true %>
<%= f.spree_email_field :contact_email,
    help: "For customer support inquiries" %>

Options:

• All standard Rails email_field options
• All common FormBuilder options

Date and Time Methods

spree_date_field

Creates a date picker input field.

<%= f.spree_date_field :available_on %>
<%= f.spree_date_field :discontinue_on,
    help: "Date when product will be discontinued" %>

Options:

• All standard Rails date_field options (:min, :max)
• All common FormBuilder options

spree_datetime_field

Creates a datetime picker input field.

<%= f.spree_datetime_field :published_at %>
<%= f.spree_datetime_field :sale_starts_at, required: true %>

Options:

• All standard Rails datetime_field options
• All common FormBuilder options

Text Area Methods

spree_text_area

Creates a textarea with auto-grow functionality (expands as you type).

<%= f.spree_text_area :description %>
<%= f.spree_text_area :notes, rows: 10 %>
<%= f.spree_text_area :meta_description,
    help: "Used for SEO, maximum 160 characters" %>

Options:

• :rows - Number of visible rows (default: 5)
• :data - Data attributes (default includes auto-grow Stimulus controller)
• All standard Rails text_area options
• All common FormBuilder options

Auto-grow behavior: By default, the textarea automatically grows as the user types. This uses the textarea-autogrow Stimulus controller.

spree_rich_text_area

Creates a rich text editor using Trix.

<%= f.spree_rich_text_area :description %>
<%= f.spree_rich_text_area :content, label: "Page Content" %>

Features:

• WYSIWYG editing
• Basic formatting (bold, italic, lists, links)
• File attachments via Active Storage
• All common FormBuilder options

Select Methods

spree_select

Creates a select dropdown field.

<%= f.spree_select :status,
    ['draft', 'active', 'archived'],
    {},
    {} %>

<%= f.spree_select :tax_category_id,
    Spree::Category.pluck(:name, :id),
    { include_blank: 'Select Tax Category' } %>

With autocomplete:

<%= f.spree_select :country_id,
    Spree::Country.pluck(:name, :id),
    { autocomplete: true } %>

Parameters:

1. method - The attribute name
2. choices - Array of options
3. options - Select options (:include_blank, :prompt, :autocomplete)
4. html_options - HTML attributes (:class, :data, :disabled)

Options:

• :autocomplete - Enables searchable dropdown with autocomplete functionality
• All standard Rails select options
• All common FormBuilder options

spree_collection_select

Creates a select dropdown from a collection of objects.

<%= f.spree_collection_select :shipping_category_id,
    ShippingCategory.all,
    :id,
    :name,
    { include_blank: true },
    {} %>

<%= f.spree_collection_select :tax_category_id,
    TaxCategory.all,
    :id,
    :name,
    { autocomplete: true, required: true },
    {} %>

Parameters:

1. method - The attribute name
2. collection - ActiveRecord collection or array of objects
3. value_method - Method to call for option value (e.g., :id)
4. text_method - Method to call for option text (e.g., :name)
5. options - Select options (:include_blank, :autocomplete)
6. html_options - HTML attributes

Options:

• :autocomplete - Enables searchable dropdown
• All standard Rails collection_select options
• All common FormBuilder options

Checkbox and Radio Methods

spree_check_box

Creates a styled checkbox with custom controls.

<%= f.spree_check_box :active %>
<%= f.spree_check_box :featured, label: "Feature on homepage" %>
<%= f.spree_check_box :accept_terms, required: true %>

Options:

• All standard Rails check_box options
• All common FormBuilder options

Styling: Uses custom control classes for consistent appearance across the admin interface.

spree_radio_button

Creates a styled radio button with custom controls.

<%= f.spree_radio_button :status, 'draft', id: 'status_draft' %>
<%= f.spree_radio_button :status, 'published', id: 'status_published' %>

Parameters:

1. method - The attribute name
2. tag_value - The value for this radio option
3. options - Options hash (must include :id)

Options:

• :id - Required HTML ID for the radio button
• All standard Rails radio_button options
• All common FormBuilder options

File Upload Methods

spree_file_field

Creates a file upload field with image preview, drag-and-drop support, and optional cropping functionality.

<%= f.spree_file_field :image %>
<%= f.spree_file_field :logo, width: 240, height: 240 %>
<%= f.spree_file_field :avatar, crop: true %>
<%= f.spree_file_field :featured_image, width: 1200, height: 600, crop: true %>

Options:

All common FormBuilder options (:label, :required, :help, :help_bubble) are also supported.

Features:

• Drag-and-drop file upload
• Image preview after upload
• Optional image cropping with size recommendations
• Delete button to remove uploaded files
• Uses Active Storage direct upload

Example with all options:

<%= f.spree_file_field :hero_video_background,
    width: 1200,
    height: 630,
    crop: false,
    auto_submit: false,
    can_delete: true,
    help_bubble: "This video will loop in the background",
    label: 'Hero video background',
    allowed_file_types: %w[video/mp4 video/webm video/ogg] %>

Complete Form Example

Here's a complete example showing various FormBuilder methods:

<div class="card mb-6">
  <div class="card-header">
    <h5 class="card-title">
      <%= Spree.t(:general_settings) %>
    </h5>
  </div>

  <div class="card-body">
    <%= f.spree_text_field :name,
        required: true,
        help: "Product name as displayed to customers" %>

    <%= f.spree_text_field :sku,
        label: "SKU",
        help_bubble: "Stock Keeping Unit - unique product identifier" %>

    <%= f.spree_number_field :price,
        required: true,
        step: 0.01,
        min: 0 %>

    <%= f.spree_rich_text_area :description,
        help: "Detailed product description with rich formatting" %>

    <%= f.spree_collection_select :tax_category_id,
        Spree::TaxCategory.all,
        :id,
        :name,
        { include_blank: 'None', required: true },
        {} %>

    <%= f.spree_date_field :available_on,
        label: "Available Date",
        help: "Date when product becomes available for purchase" %>

    <%= f.spree_check_box :active,
        label: "Active" %>
  </div>
</div>

Error Handling

All FormBuilder methods automatically display validation errors below the field when present:

<%= f.spree_text_field :name %>

If @product.errors[:name] contains errors, they will be displayed automatically in red text below the input field.

Internationalization

Labels are automatically translated using Rails I18n. The FormBuilder looks for translations in this order:

1. Custom label passed via :label option
2. spree.{attribute_name} key
3. activerecord.attributes.spree/{model_name}.{attribute_name} key

Example translations:

# config/locales/en.yml
en:
  spree:
    name: "Product Name"
    sku: "SKU Code"
  activerecord:
    attributes:
      spree/product:
        available_on: "Available On Date"
        discontinue_on: "Discontinuation Date"

Styling and CSS Classes

All FormBuilder methods use consistent styling:

• Form groups: Each field is wrapped in a .form-group div
• Input classes: Text inputs use .form-control class
• Select classes: Dropdowns use .custom-select class
• Checkboxes/Radios: Use .custom-control, .custom-checkbox, .custom-radio classes

You can add additional classes via the :class option:

<%= f.spree_text_field :name, class: 'form-control-lg' %>

Best Practices