Primitives

We use Form Primitives as the building blocks for the “field” and “group” controls. While we recommend using our pre-defined “field” and “group” controls because they provide built-in accessibility support, you can use the Form Primitives to implement custom layouts or controls as necessary.

More details on how to assemble form components in larger form patterns can be found in the form patterns documentation.

• Form::Label is the label associated with the form control
• Form::HelperText is an optional text used to help understand what the field is intended for
• Form::Error is the error message shown in case of failed validation of the field
• Form::Indicator is the indicator for "Required" or "Optional" inputs
• Form::Legend is the legend associated to the fieldset
• Form::Field is the generic container for control, label, helper text and error messaging
• Form::Fieldset is the generic container to group multiple fields with label, helper text, and error messaging
• Form::CharacterCount is optionally used to display the number of characters entered in a field, the maximum or minimum number of characters allowed, or a custom message communicating the relationship between the count and the maximum or minimum length.
  • CharacterCount is only used in fields that accept text values (TextInput, Textarea, MaskedInput).

How to use this component

Form::Label

The default invocation requires text to be passed and a controlId argument (the ID of the form control associated with the label).

<Hds::Form::Label @controlId="control-ID">
  My label
</Hds::Form::Label>

Pass an isRequired argument, when user input is required for the associated form control.

<Hds::Form::Label @controlId="control-ID" @isRequired={{true}}>
  My label
</Hds::Form::Label>

Pass an isOptional argument, when the user input is optional for the associated form control.

<Hds::Form::Label @controlId="control-ID" @isOptional={{true}}>
 My label
</Hds::Form::Label>

If the label needs to contain more than just text, it’s possible to pass structured content to component. While the correct text styling is applied to the component’s container, the layout of the content inside the component is the responsibility of the product team.

<Hds::Form::Label @controlId="control-ID">
  <span>Some text</span>
  <Hds::Badge @size="small" @text="Some badge" @color="highlight" />
</Hds::Form::Label>

Form::HelperText

The default invocation requires text to be passed and a controlId argument.

The controlId value is used to generate an ID, prefixed with helper-text-, so that the ID can be referenced in the aria-describedby attribute of the form control. If no controlId is provided, no ID is generated. If needed, it can be passed directly as an HTML attribute.

<Hds::Form::HelperText @controlId="helper-text-first">
  This is some helper text
</Hds::Form::HelperText>

If the helper text needs to contain more than just text, use the block form of the component. While the correct styling is applied to the component itself, the nested components may need additional styling and are the responsibility of the product team.

<Hds::Form::HelperText @controlId="control-ID">
  Some text with a
  <Hds::Link::Inline @route="show" @model="components/link/inline">
  Hds::Link::Inline</Hds::Link::Inline>,
  or <code>some formatted code</code>
  or a <strong>strong message</strong>.
</Hds::Form::HelperText>

Form::CharacterCount

The default invocation requires a controlId argument referencing a valid <input> or <textarea> element and a @value argument storing the value of the associated form control.

The controlId value is used to generate an ID, prefixed with character-count-, so that the ID can be referenced in the aria-describedby attribute of the form control.

<input type="text" aria-label="input with default character count" id="input-character-count-default" value={{this.value1}} {{on "input" (fn this.updateValue "value1")}}/>
<Hds::Form::CharacterCount @controlId="input-character-count-default" @value={{this.value1}}/>

If the user input needs to be limited to a certain number of characters, use @maxLength to guide the user in meeting the length requirements. This property does not restrict the users from entering characters over the limit. To define the maximum string length that the user can enter, set maxlength attribute on the associated input field.

<input type="text" aria-label="input with max length count" id="input-character-count-max" value={{this.value2}} {{on "input" (fn this.updateValue "value2")}}/>
<Hds::Form::CharacterCount @maxLength={{10}} @controlId="input-character-count-max" @value={{this.value2}}/>

If the user input is required to have a certain number of characters, use @minLength to guide the user in meeting the length requirements.

<input type="text" aria-label="input with min length count" id="input-character-count-min" value={{this.value3}} {{on "input" (fn this.updateValue "value3")}}/>
<Hds::Form::CharacterCount @minLength={{3}} @controlId="input-character-count-min" @value={{this.value3}}/>

When the user input needs to be in a certain range, use both @minLength and @maxLength to guide the user in meeting the length requirements.

<input type="text" aria-label="input with min and max length count" id="input-character-count-min-max" value={{this.value4}} {{on "input" (fn this.updateValue "value4")}}/>
<Hds::Form::CharacterCount @minLength={{3}} @maxLength={{10}} @controlId="input-character-count-min-max" @value={{this.value4}}/>

Custom message

For custom messages, you can use the following arguments to build a relevant message: currentLength (the current number of characters in the associated form control), maxLength (the maximum number of characters allowed in the associated form control), minLength (the minimum number of characters required in the associated form control), remaining (the difference between maxLength and currentLength), and shortfall (the difference between currentLength and minLength).

<input type="text" aria-label="input with min and max length count" id="input-character-count-custom" value={{this.value5}} {{on "input" (fn this.updateValue "value5")}}/>
<Hds::Form::CharacterCount @maxLength={{20}} @controlId="input-character-count-custom" @value={{this.value5}} as |CC|>
  {{CC.remaining}} characters remaining
</Hds::Form::CharacterCount>

Form::Error

The default invocation requires text to be passed and a controlId argument.

The controlId value will be used to generate an ID, prefixed with error-, so that this ID can be referenced in the aria-describedby attribute of the form control. If no controlId is provided, no ID is generated. If needed, it can be passed directly as an HTML attribute.

<Hds::Form::Error @controlId="error-message-first">This is a simple error message</Hds::Form::Error>

If the error is made up of multiple messages, it’s possible to iterate over a collection of error messages.

<Hds::Form::Error @controlId="control-ID" as |Error|>
  {{#each this.SAMPLE_ERROR_MESSAGES as |message|}}
    <Error.Message>{{message}}</Error.Message>
  {{/each}}
</Hds::Form::Error>

Form::Indicator

If no isRequired/isOptional argument is provided, the component will not render anything.

Required

Pass an isRequired argument, to render a Required Indicator.

<Hds::Form::Indicator @isRequired={{true}} />

Optional

Pass an isOptional argument, to render an Optional Indicator.

<Hds::Form::Indicator @isOptional={{true}} />

Form::Legend

The default invocation requires text to be passed.

<Hds::Form::Legend>My legend</Hds::Form::Legend>

Required

Pass an isRequired argument, when user input is required for the associated form control.

<Hds::Form::Legend @isRequired={{true}}>My legend</Hds::Form::Legend>

Optional

Pass an isOptional argument, when user input is optional for the associated form control.

<Hds::Form::Legend @isOptional={{true}}>My legend</Hds::Form::Legend>

Structured content

If the legend needs to contain more than just text, it’s possible to pass structured content to component. While the correct text styling is applied to the component’s container, the layout of the content inside the component is the responsibility of the product team.

<Hds::Form::Legend>
  <span>Some text</span>
  <Hds::Badge @size="small" @text="Some badge" @color="highlight" />
</Hds::Form::Legend>

Form::Field

The default invocation includes a set of contextual components, a control (in this case a text input) with hashed values passed back to it, and a @layout argument. Depending on the context, you may want to pass just the label, or the label and the helper text, while the error message is likely conditional to the validation of the input provided by the user. The arguments id and ariaDescribedBy are automatically generated by the component and passed back to the control.

The layout of the content inside the "control" container is the responsibility of the product team.

<Hds::Form::Field @layout="vertical" @isRequired={{true}} as |F|>
  <F.Label>This is the label</F.Label>
  <F.HelperText>This is the helper text</F.HelperText>
  <F.Control>
    <!--add your control here-->
    <input
      type="email"
      id={{F.id}}
      value="jane.doe@email.com"
      class="my-custom-class"
      aria-describedby={{F.ariaDescribedBy}}
    />
  </F.Control>
  <F.Error>This is the error</F.Error>
</Hds::Form::Field>

Form::Fieldset

The default invocation includes a set of contextual components, one or more fields (in this case radio buttons within a label), and a @layout argument. Depending on the context, you may want to pass just the legend, just the helper text, both or none, while the error message is likely conditional to the validation of the inputs provided by the user.

The layout of the content inside the "control" container is the responsibility of the product team.

<Hds::Form::Fieldset @layout="horizontal" @isRequired={{true}} as |F|>
  <F.Legend>This is the legend</F.Legend>
  <F.HelperText>This is the helper text</F.HelperText>
  <!-- add your fields here -->
  <F.Control>
    <label for="my-group-checkbox1" class="my-custom-class">
      <input type="checkbox" id="my-group-checkbox1" checked="checked" />
      selection #1
    </label>
  </F.Control>
  <F.Control>
    <label for="my-group-checkbox2" class="my-custom-class">
      <input type="checkbox" id="my-group-checkbox2" />
      selection #2
    </label>
  </F.Control>
  <F.Error>This is the error</F.Error>
</Hds::Form::Fieldset>

Component API

Form::Label

Form::HelperText

Form::CharacterCount

Form::Error

Form::Indicator

Form::Legend

Form::Field

Contextual components

Control, label, helper text, and error content are passed to the field as yielded components, using the Label, HelperText, Control, CharacterCount, and Error keys.

Form::Fieldset

Contextual components

Control, Label, HelperText, and Error content are passed to the field as yielded components. The component also exposes two hashed methods, id and ariaDescribedBy.

Label

• We recommend keeping labels clear and concise, about 1-3 words. They should not consist of full sentences.
• All inputs need a visible label to let users know what the purpose of the input is. This is required for accessibility by WCAG 3.2.2

Helper Text

• Use helper text to give the user extra details about the data you’re asking them to input, e.g., formatting requirements such as MM-DD-YYYY.

Errors

• Error messages should provide the user with enough context to guide them in resolving the error.
• Keep labels and legends short and to the point (ie. "Select one option")
• Avoid overt politeness; don’t use "please" or "thank you" in your messaging.
• If an input is errored out, it is visually identifiable with associated error messaging by WCAG 3.3.1.
• If an input is errored out, the messaging needs to be clear for the user to rectify the issue by WCAG 3.3.3.
• If the data inputted is related to legal or financial information, the user is given an opportunity to review, confirm or rectify the information before finalizing its submission by WCAG 3.3.4
• Use roles or properties to help identify statuses so that they are accessible by assistive technologies without receiving focus by WCAG 4.1.3.

Conformance rating

Form Primitives aren’t conformant until used in conjunction with the other components that will make them conformant.

Known issues

If a link is used within a label, helper text, or error text, it will not be presented as a link to the user with a screen reader; only the text content is read out. As such, care should be used when considering this feature.

Applicable WCAG Success Criteria

This section is for reference only, some descriptions have been truncated for brevity. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.21.0

Form::Legend - Added @id argument.

Form::Label - Added @hiddenText argument, which adds visually hidden text inside the label.

4.20.1

Form::Field - Fixed focus order a11y issue for helper text links with @layout of flag

4.20.0

Form::Label - Forced the for HTML attribute to be converted to a string