Skip to main contentPrimer

FormControl

readyNot reviewed for a11y
Lookbook|Source
This page may be removed. Primer plans to move all Rails component documentation to Lookbook.
The FormControl component is part of the Primer ViewComponents forms framework. If you are building a form, please consider using the framework instead of this standalone component.

Description

Wraps an input (or arbitrary content) with a label above and a caption and validation message beneath.

NOTE: This FormControl component is designed for wrapping inputs that aren't supported by the Primer forms framework.

Accessibility

Because FormControl does not manage the actual <input> element, it cannot semantically connect the input and its associated label. For this and other reasons, consumers are highly encouraged to use Primer's pre-made form components like TextField, etc, ideally via the Primer forms framework.

Users of the FormControl component will need to manually connect the label using the for: attribute, eg:

<%= form_with(url: "/path/somewhere") do |f| %>
  <%= render(Primer::Alpha::FormControl.new(label_arguments: { for: "bar" })) do |component| %>
    <% component.with_input do |input_arguments| %>
      <%= f.text_field(:bar, **input_arguments) %>
    <% end %>
  <% end %>
<% end %>

Note that the name of the field, :bar, is passed to both the Rails #text_field method and as part of the label_arguments passed to the FormControl constructor.

Similarly, FormControl cannot automatically connect the <input> element to the caption and validation message elements. The component attempts to mitigate this by including the correct aria-describedby attribute in the hash it yields to the block passed to #with_input. In the example above, input_arguments[:aria][:describedby] contains the HTML IDs for both the caption and validation message elements, and can be passed directly to Rails' form helper methods. If the input being wrapped is not generated by a Rails form helper, care must be taken to set aria-describedby manually on the input element.

Arguments

NameRequiredDescription
label
String

Label text displayed above the input.

caption
String

Describes the field and what sort of input it expects. Displayed below the input. Note that the caption slot is also available and takes precedence over this argument when provided.

validation_message
String

A string displayed in red between the caption and the input indicating the input's contents are invalid.

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.

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.

full_width
Boolean

When set to true, the form control will take up all the horizontal space allowed by its container.

label_arguments
Hash

HTML attributes to attach to the <label> element that labels the input.

system_arguments
Hash

Slots

caption

Describes the field and what sorts of input it expects. Displayed below the input. Note that this slot takes precedence over the caption: argument in the constructor.

input

The input content. Yields a set of System arguments that should be added to the input.

Methods

required? -> Boolean

Whether or not this input is marked as required.

visually_hide_label? -> Boolean

Whether or not to hide the label visually. The label will still be visible to screen readers.

full_width? -> Boolean

Whether or not the form control should take up all the horizontal space allowed by its container.