Skip to main content

Form Fields

form_field adds an input inside a cm_section of a new or edit form.

Quick example​

cm_section "Details" do
form_field :title, input_type: :string
form_field :status, input_type: :single_select, collection: ["draft", "published", "archived"]
form_field :published_at, input_type: :date
form_field :body, input_type: :rich_text
end

Options​

form_field(field_name, input_type = :string, attributes = {})
NameTypeDescription
field_nameSymbolThe name of the field (usually a model attribute).
input_typeSymbolThe input type. Can be :integer, :decimal, :string, :single_select, :multi_select, :date, :date_time, :text, :phone, :switch, :custom_single_select, :checkbox_group, :single_file_upload, :multi_file_upload, :hidden, :rich_text, :check_box, :radio_button, :custom_string, :custom_date, :radio_button_group, :color_picker, or :email. Default: :string.
labelStringCustom label for the field. Defaults to titleized field name.
collectionArrayCollection of options for select fields.
disabledProcLambda that takes the current object and returns boolean to disable the field. Default: ->(_arg) { false }.
helper_methodSymbolCustom helper method defined in custom_helper.rb to provide collection or custom rendering.
placeholderStringPlaceholder text for the input. Defaults to "Enter {field}" or "Select {field}" based on input type.
display_ifProcLambda that takes the current object and returns boolean to conditionally display the field. Default: ->(_arg) { true }.
html_attrsHashHTML attributes for the input element. Default: {}.
col_sizeIntegerColumn size in grid layout.
options_urlStringURL for fetching options asynchronously (for custom select fields).
helper_textStringHelper text displayed below the input field.
image_previewBooleanShow image preview for file upload fields. Default: false.
can_create_new_entityBooleanAllow creating a new entity from select fields via a drawer form. Default: false.
is_requiredBooleanMark field as required. If omitted, the field is automatically marked required when the model has a presence validator for it, or when the field is a non-optional belongs_to foreign key. Default: false when no automatic condition is met.
default_valueProc, String, SymbolDefault value for the field, can be a string, symbol or a proc. proc takes an argument and returns a value. symbol will be called as a method from custom_helper.rb.
timezoneString, Symbol, ProcTimezone to use when displaying and submitting :date_time fields. A String is used as a timezone name (e.g. 'Asia/Kolkata'), a Symbol calls a helper method from custom_helper.rb with (record, field_name), and a Proc receives the record and returns the timezone string.
label_linkHashRenders a link next to the field label. Accepts :url (required), :text (default: 'Download'), :icon (CSS icon class), and :html_attrs (extra HTML attributes for the link). The link opens in a new tab by default and downloads the file at :url.

Required fields​

Catalyst automatically marks a form field as required when:

  • the model declares validates :field_name, presence: true
  • the field is a non-optional belongs_to foreign key (for example, user_id for belongs_to :user)

You can still explicitly mark a field as required using is_required: true, even when the model has no presence validator. The same logic applies to nested form fields based on the associated model.

Recipes​

Basic form fields​

form_field :title, input_type: :string
form_field :description, input_type: :text
form_field :email, input_type: :email

Select fields​

form_field :status, input_type: :single_select, collection: ['draft', 'published', 'archived']
form_field :category_id, input_type: :single_select, helper_method: :category_collection
form_field :tag_ids, input_type: :multi_select, helper_method: :tag_collection
form_field :category_id, input_type: :single_select, helper_method: :category_collection,
can_create_new_entity: true # "create new" drawer inside the select

Radio buttons and checkboxes​

form_field :preference, input_type: :radio_button_group,
collection: [["Option A", "option_a"], ["Option B", "option_b"]]
form_field :role_ids, input_type: :checkbox_group, helper_method: :role_collection
form_field :terms_accepted, input_type: :check_box

Switch and hidden fields​

form_field :is_featured, input_type: :switch, label: "Featured?"
form_field :job_id, input_type: :hidden # submitted but never rendered

Date and datetime fields​

form_field :published_at, input_type: :date
form_field :event_time, input_type: :date_time
form_field :event_time, input_type: :date_time, timezone: 'Asia/Kolkata'
form_field :event_time, input_type: :date_time, timezone: ->(record) { record.user.timezone }
form_field :event_time, input_type: :date_time, timezone: :record_timezone # calls record_timezone(record, field_name) in custom_helper.rb

File upload fields​

form_field :avatar, input_type: :single_file_upload, image_preview: true
form_field :documents, input_type: :multi_file_upload

Field with conditional display​

form_field :admin_notes, input_type: :text, display_if: ->(record) { current_user.admin? }

Disabled field​

A field the user can see but not change β€” the lambda receives the record:

form_field :job_title, input_type: :string, disabled: ->(_) { true }, label: "Job"
form_field :name, input_type: :string, disabled: ->(record) { record.is_featured? }

Pair disabled with helper_text to explain why the field is locked.

Two fields per row​

col_size puts fields side by side in the 12-column grid:

cm_section "Duration" do
form_field :start_date, input_type: :date, col_size: 6
form_field :end_date, input_type: :date, col_size: 6
end

Async select options​

options_url fetches the options of a select over AJAX instead of rendering them in the page β€” see Select options:

form_field :city_id, input_type: :single_select, options_url: "/cm_admin/cities/fetch_options"

Date constraints via HTML attributes​

html_attrs lands on the input element, so Stimulus/data attributes work:

form_field :published_at, input_type: :date, label: "Publish Date",
helper_text: "Today or a past date only.",
html_attrs: { data: { max_date: "today" } }

Field with helper text and required​

form_field :password, input_type: :string, helper_text: 'Minimum 8 characters', is_required: true

Field with HTML attributes​

form_field :bio, input_type: :text, html_attrs: { 'data-custom' => 'value' }

Rich text and color picker​

form_field :content, input_type: :rich_text
form_field :theme_color, input_type: :color_picker

Field with default value​

form_field :name, input_type: :string, default_value: 'draft'
form_field :name, input_type: :string, default_value: :user_name
form_field :name, input_type: :string, default_value: ->(record) { record.name }
form_field :resume, input_type: :single_file_upload,
label_link: { url: 'https://example.com/resume-template.docx', text: 'Download Template', icon: 'fa fa-download' }