Primer ViewComponents v0.35.1

Previews

No matching results.

Check Box

Check boxes are true/false inputs rendered as <input type="checkbox"> in HTML.

Schemes

Check boxes can submit values to the server using one of two schemes, either :array or :boolean (the default). Check boxes with a scheme of :boolean function like normal HTML check boxes. If they are checked, a value of "1" is sent to the server; if they are unchecked, a value of "0" is sent to the server. The checked and unchecked values can be customized via the :value and :unchecked_value arguments respectively.

Whereas :boolean check boxes must have unique names, :array check boxes all have the same name. On form submission, Rails will aggregate the values of the check boxes with the same name and provide them to the controller as an array. If :scheme: is :array, the :value argument must also be provided. The :unchecked_value argument is ignored. If a check box is checked on submit, its corresponding value will appear in the array. If it is not checked, its value will not appear in the array.

Caption templates

Caption templates for :array-type check boxes work a little differently than they do for other input types. Because the name must be the same for all check boxes that make up an array, caption template file names are comprised of both the name and the value of each check box. For example, a check box with the name foo and value bar must have a caption template named foo_bar_caption.html.erb.

Nested Forms

Check boxes can have "nested" forms that are rendered below the caption. A common use-case is a form that is hidden until the check box is checked. Nested forms are indented slightly to align with the label and caption.

Define a nested form via the #nested_form method, which is expected to return an instance of a Primer form (see the usage section below).

Any fields defined in the nested form are submitted along with the parent form's fields.

NOTE: Check boxes do not automatically show or hide nested forms. If such behavior is desired, it must be done by hand.

Usage

class ExampleForm < ApplicationForm
  form do |example_form|
    example_form.check_box(attributes) do |check_box|
      check_box.nested_form do |builder|
        AnotherPrimerForm.new(builder)
      end
    end
  end
end

Arguments

Name Type Description
value String On form submission, this value will be sent to the server if the check box is checked. Defaults to "1".
unchecked_value String On form submission, this value will be sent to the server if the check box is not checked. Defaults to "0".
scheme Symbol Controls how check box values are submitted to the server. One of :array or :boolean..

Common arguments

Name Type Description
name String Value for the HTML name attribute.
id String Value for the HTML id attribute.
class String CSS classes to include in the input's HTML class attribute. Exists for compatibility with Rails form builders.
classes Array CSS classes to include in the input's HTML class attribute. Combined with the :class argument. The list may contain strings, hashes, or nil values, and is automatically cleaned up by Primer's class_name helper (nils, falsy entries, and blank strings are ignored).
caption String A string describing the field and what sorts of input it expects. Displayed below the input.
label String Label text displayed above the input.
visually_hide_label Boolean When set to true, hides the label. Although the label will be hidden visually, it will still be visible to screen readers.
disabled Boolean When set to true, the input will not accept keyboard or mouse input.
hidden Boolean When set to true, visually hides the field.
invalid Boolean If set to true, the input will be rendered with a red border. Implied if validation_message is truthy. This option is set to true automatically if the model object associated with the form reports that the input is invalid via Rails validations. It is provided for cases where the form does not have an associated model. If the input is invalid as determined by Rails validations, setting invalid to false will have no effect.
validation_message String A string displayed between the caption and the input indicating the input's contents are invalid. This option is, by default, set to the first Rails validation message for the input (assuming the form is associated with a model object). Use validation_message to override the default or to provide a validation message in case there is no associated model object.
label_arguments Hash Attributes that will be passed to Rails' builder.label method. These can be HTML attributes or any of the other label options Rails supports. They will appear as HTML attributes on the <label> tag.
scope_name_to_model Boolean Default true. When set to false, prevents the model name from prefixing the field name. For example, if the field name is my_field, Rails will normally emit an HTML name attribute of model[my_field]. Setting scope_name_to_model to false will cause Rails to emit my_field instead.
scope_id_to_model Boolean Default true. When set to false, prevents the model name from prefixing the field ID. For example, if the field name is my_field, Rails will normally emit an HTML ID attribute of model_my_field. Setting scope_id_to_model to false will cause Rails to emit my_field instead.
required Boolean Default false. When set to true, causes an asterisk (*) to appear next to the field's label indicating it is a required field. Note that this option explicitly does not add a required HTML attribute. Doing so would enable native browser validations, which are inaccessible and inconsistent with the Primer design system.
aria Hash Key/value pairs that represent Aria attributes and their values. Eg. aria: { current: true } becomes aria-current="true".
data Hash Key/value pairs that represent data attributes and their values. Eg. data: { foo: "bar" } becomes data-foo="bar".
system_arguments Hash A hash of attributes passed to the underlying Rails builder methods. These options may mean something special depending on the type of input, otherwise they are emitted as HTML attributes. See the Rails documentation for more information. In addition, the usual Primer utility arguments are accepted in system arguments. For example, passing mt: 2 will add the mt-2 class to the input. See the Primer system arguments docs for details.
name String Value for the HTML name attribute.

Methods

#nested_form

Name Type Description
system_arguments Hash System arguments that will be applied to a <div> element that wraps the form.
block Proc This block is yielded the Rails builder object and is expected to return the nested form object, an instance of Primer::Forms::Base.

Examples