File Input

Usage

The File Input component uses the native HTML input with type="file" under the hood but adds visual styling to match other HDS components.

Browser inconsistency

Because the File Input is based on the native HTML input, the content and visual appearance may vary slightly across browsers.

Truncation

Truncation is built into the native component and uses the width of the container to determine when the text gets truncated. It is not based on a character limit.

Multiple files

Multiple files can be added at once when the multiple attribute is enabled in code. When more than one file is selected, the text will change to show the number of files you’ve selected, e.g., “2 files”. The exact language used may differ between browsers.

How to use this component

The File Input component uses the native HTML input with type="file" under the hood but adds visual styling to match other HDS components.

There are two ways to use the File Input component:

• Form::FileInput::Base—the Base component: just the <input type="file"> control.
• Form::FileInput::Field—the Field component: the <input type="file"> control, with label, helper text, and error messaging (in a wrapping container).

We recommend using the Field component as it provides built-in accessibility functionality. Use the Base component if you need to achieve custom layouts or for special use cases not covered by the Field component.

Form::FileInput::Field

<Hds::Form::FileInput::Field as |F|>
  <F.Label>Upload a file</F.Label>
</Hds::Form::FileInput::Field>

Helper text

You can add extra information to the field using helper text. When helper text is added, the component automatically adds an aria-describedby attribute to the input control, associating it with the automatically generated ID of the helper text element.

<Hds::Form::FileInput::Field as |F|>
  <F.Label>Upload a file</F.Label>
  <F.HelperText>File size should be a maximum of 2 MB.</F.HelperText>
</Hds::Form::FileInput::Field>

Extra content in label and helper text

The Label and HelperText contextual components used in the Field component yield their content. This means you can also pass structured content.

<Hds::Form::FileInput::Field as |F|>
  <F.Label>Upload a file <Hds::Badge @size="small" @text="Beta" /></F.Label>
  <F.HelperText>This is an <Hds::Link::Inline @href="#">experimental feature</Hds::Link::Inline>.</F.HelperText>
</Hds::Form::FileInput::Field>

Required vs. optional

Use the @isRequired and @isOptional arguments to add a visual indication that the field is "required" or "optional".

<Hds::Form::FileInput::Field @isRequired={{true}} as |F|>
  <F.Label>Upload a file</F.Label>
  <F.HelperText>File size should be a maximum of 2 MB.</F.HelperText>
</Hds::Form::FileInput::Field>
<br />
<Hds::Form::FileInput::Field @isOptional={{true}} as |F|>
  <F.Label>Upload a file</F.Label>
  <F.HelperText>File size should be a maximum of 2 MB.</F.HelperText>
</Hds::Form::FileInput::Field>

Validation

To indicate a field is invalid, provide an error message using the Error contextual component.

<Hds::Form::FileInput::Field as |F|>
  <F.Label>Upload a file</F.Label>
  <F.Error>The provided file format is not valid.</F.Error>
</Hds::Form::FileInput::Field>

Add more than one error message using the more specific Message contextual component.

<Hds::Form::FileInput::Field as |F|>
  <F.Label>Upload a file</F.Label>
  <F.Error as |E|>
    <E.Message>File size should be a maximum of 2 MB.</E.Message>
    <E.Message>Dimensions should be a minimum of 100px × 100px.</E.Message>
  </F.Error>
</Hds::Form::FileInput::Field>

Custom control ID

To use a custom ID value instead of the one automatically generated by the component, pass the @id argument to the Field component.

<Hds::Form::FileInput::Field @id="my-control" as |F|>
  <F.Label>Upload a file</F.Label>
</Hds::Form::FileInput::Field>

Additional aria-describedby

Pass an @extraAriaDescribedBy argument to the Field component to connect one or more extra elements describing the field to the control. This provides extra ID values to the aria-describedby attribute of the control, in addition to those automatically generated by the component.

<Hds::Form::FileInput::Field @extraAriaDescribedBy="my-extra-element-ID" as |F|>
  <F.Label>Upload a file</F.Label>
</Hds::Form::FileInput::Field>

HTML native attributes

This component supports use of ...attributes. This means you can use all the standard HTML attributes of the <input> element. This can be useful in case you want to add specific native behaviors to the Field, that are not exposed directly by the component (e.g., providing a name for the control, or adding min, max, minlength, maxlength, or pattern attributes to it).

<Hds::Form::FileInput::Field name="user-password" as |F|>
  <F.Label>Upload a file</F.Label>
</Hds::Form::FileInput::Field>

Form::FileInput::Base

The Base component is intended for rare cases where the Field component can’t be used and a custom implementation is needed. Most of the details for the Field component also apply to the Base component, but see the Component API for more details.

<Hds::Form::FileInput::Base />

Component API

The File Input component has two different variants with their own APIs:

• Form::FileInput::Base—the base component: the <input type="file"> control
• Form::FileInput::Field—the field parent component: the <input type="file"> control, with label, helper text, and error messaging (in a wrapping container)

Form::FileInput::Base

Form::FileInput::Field

Contextual components

Label, HelperText, and Error content are passed to the field as yielded components.

Anatomy

States

Conformance rating

When used as recommended, there should not be any WCAG conformance issues with this component.

Applicable WCAG Success Criteria

This section is for reference only. 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.