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 = {})
| Name | Type | Description |
|---|---|---|
field_name | Symbol | The name of the field (usually a model attribute). |
input_type | Symbol | The 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. |
label | String | Custom label for the field. Defaults to titleized field name. |
collection | Array | Collection of options for select fields. |
disabled | Proc | Lambda that takes the current object and returns boolean to disable the field. Default: ->(_arg) { false }. |
helper_method | Symbol | Custom helper method defined in custom_helper.rb to provide collection or custom rendering. |
placeholder | String | Placeholder text for the input. Defaults to "Enter {field}" or "Select {field}" based on input type. |
display_if | Proc | Lambda that takes the current object and returns boolean to conditionally display the field. Default: ->(_arg) { true }. |
html_attrs | Hash | HTML attributes for the input element. Default: {}. |
col_size | Integer | Column size in grid layout. |
options_url | String | URL for fetching options asynchronously (for custom select fields). |
helper_text | String | Helper text displayed below the input field. |
image_preview | Boolean | Show image preview for file upload fields. Default: false. |
can_create_new_entity | Boolean | Allow creating a new entity from select fields via a drawer form. Default: false. |
is_required | Boolean | Mark 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_value | Proc, String, Symbol | Default 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. |
timezone | String, Symbol, Proc | Timezone 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_link | Hash | Renders 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_toforeign key (for example,user_idforbelongs_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 }
Field with a label linkβ
form_field :resume, input_type: :single_file_upload,
label_link: { url: 'https://example.com/resume-template.docx', text: 'Download Template', icon: 'fa fa-download' }