Primitives

Form primitives are used to compose form fields.

• Form::Label is the label associated with the form control
• Form::HelperText is an optional extra text used to help the user understand what the field is intended for
• Form::Error is the error message shown to the user in case of failed validation of the field
• Form::Indicator is the indicator for "Required" or "Optional" user 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

We use form primitives, internally, as the building blocks for the "field" and "group" controls. They can also be used in special cases when needing to implement custom layouts or controls. We recommend using our pre-defined "field" and "group" controls, as they provide built-in accessibility support.

Usage

Form::Error

While we provide the structure and visual consistency for errors, the messaging and functionality are to be handled by the product teams.

Types of validation

Use a combination of client side and server side validation for the best user experience. Catching basic errors with client side validation allows the user to quickly resolve the error before submitting the form.

Client side validation

Client side validation, sometimes also referred to as inline validation, is an initial check that happens in the browser to ensure required fields are filled out and that the value is in the correct format. Learn more about client side validation.

Server side validation

Server side validation provides a more thorough check on the server once the data has been submitted and helps keep our applications safe.

When using server side validation, display an AlertInline in the Critical variant above the form listing all errors with links to each invalid field.

Content

Form::Label

• We recommend keeping labels clear and concise, about 1-3 words. They should not consist of full sentences.
• 3.3.2 Labels or Instructions (A): Labels or instructions are provided when content requires user input.

Form::HelperText

• Use Form::HelperText when needing to provide the user with extra details about the data you’re asking them to input, eg. formatting requirements such as MM-DD-YYYY.

Form::Error

• Error messages need to provide the user with enough context to guide them in resolving the error.
• Keep messages short and to the point.
• eg. "Enter a valid email address.", "Resource Share ARN starts with arn-"
• Avoid overt politeness; don’t use "please" or "thank you" in your messaging.
• 3.3.1 Error Identification (A): If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text.
• 3.3.3 Error Suggestion (AA): If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user, unless it would jeopardize the security or purpose of the content.
• 3.3.4 Error Prevention (Legal, Financial, Data) (AA): For web pages that cause legal commitments or financial transactions for the user to occur, that modify or delete user-controllable data in data storage systems, or that submit user test responses, at least one of the following is true: submissions are reversible, data is checked and user is provided an opportunity to correct them, a mechanism is available for reviewing, confirming and correcting the information before finalizing the submission.
• 4.1.3 Status Messages(AA): In content implemented using markup language, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus.

Refer to HashiCorp’s Style, Language, and Voice Guidelines (internal only) for more content tips.

How to use this component

Form::Label

The most basic 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 most basic 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 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::HelperText @controlId="control-ID">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::Error

The most basic 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="control-ID">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 @model.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.

Pass an isRequired argument, to render a Required indicator.

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

Pass an isOptional argument, to render an Optional indicator.

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

Form::Legend

The most basic invocation requires text to be passed.

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

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

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

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

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

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

A basic 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

A basic 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::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, Error keys.

Form::Fieldset

Contextual components

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

Conformance rating

Form primitives aren’t conformant until used in conjunction with the other components/elements 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 these components, please let us know by submitting an issue.