What does the component do?

A file selector is a component that allows users to select and upload files from their device.

When should the component be used?

• To allow users to upload files, such as documents, images or videos.
• To complete forms that require file attachments.
• To collect files for storage, processing or sharing.

Rules

• Users should be able to remove files.
• The progress of the file upload can be displayed to users, especially for larger files.
• The file selector supports both drag-and-drop and browsing files via a button. Depending on the available space, the appropriate variant should be selected.

Playground

Examples

The sbb-file-selector is a component which allows user to select one or more files from storage devices.
When files are selected, they appear as a list below the button/dropzone area.
For each file, the name and the size are displayed and an icon allows for deletion.

Variants

It has two different display options based on the value of the variant property:
by default, a sbb-button is displayed, which mimics the native <input type="file"/>.

<sbb-file-selector></sbb-file-selector>

Instead, if the variant property is set to dropzone, the sbb-button is shown within a "drag & drop" area.
In this case, it's possible to customize the area's title via the titleContent property.

<sbb-file-selector variant="dropzone" title-content="Drop file here."></sbb-file-selector>

The component has also two different sizes, m (default) and s, which can be changed using the size property.

<sbb-file-selector size="s"></sbb-file-selector>

Multiple and multipleMode

In both variants, a single file can be selected by default; this can be changed setting the multiple property to true.

<sbb-file-selector multiple></sbb-file-selector>

The value of the multipleMode property determines whether added files should overwrite existing files (default) or be appended to them (persistent).

<sbb-file-selector multiple multiple-mode="persistent"></sbb-file-selector>

Accept

The accept property can be used to force the user to select one or more specific file types;
in the next example, only images are allowed.

<sbb-file-selector accept=".png,.jpg,.jpeg"></sbb-file-selector>

Disabled

User interaction can be disabled using the disabled property.

<sbb-file-selector disabled></sbb-file-selector>

Error slot

The error named slot can be used to display an error message using the sbb-form-error component.

<sbb-file-selector variant="dropzone">
  <sbb-form-error slot="error">An error occurred during file upload.</sbb-form-error>
</sbb-file-selector>

Events

Whenever the selection changes, a fileChanged event is fired, whose event.detail property contains the list
of currently selected files. The list can also be retrieved using the getFiles() method.

Accessibility

It's possible to improve the component accessibility using the accessibilityLabel property; this will be set
as aria-label of the inner native input and read together with the visible button text.
It's suggested to have a different value for each variant, e.g.:

<sbb-file-selector accessibility-label="Select a file from hard disk"></sbb-file-selector>
<sbb-file-selector
  multiple
  accessibility-label="Select from hard disk - multiple selection allowed"
></sbb-file-selector>

Properties

Methods

Events

Slots