File Input

Allows the user to upload one or multiple files from their device. Uploads are initiated via the native OS file picker.

UsageAPI

Use File Input...

For uploading one or more files.
When space on a page is limited.
The upload functionality is not the primary action on a view/page.

Don't use File Input...

For most use cases. Use File Dropzone instead as this provides the affordance of drag and drop.
To show the progress of uploading. Use File Tile instead.

Default

File Input is built upon the native HTML <input type="file"> element, so it can accept all of the native input’s events and attributes, including onChange to get the contents of the uploaded file, or multiple to let the user select multiple files.

The File Input Label sub-component is the visible part, since we hide the native <input> and only show this <label>. For accessibility, it must have accessible text, such as visible HTML text, visually-hidden text, alt text on an image, or an aria-label.

ReactVanilla

<FileInput>
  <FileInputLabel iconPosition="left">
    Upload from device
    <Icon iconType="upload" />
  </FileInputLabel>
</FileInput>

<FileInput>
  <FileInputLabel iconPosition="left">
    Upload from device
    <Icon iconType="upload" />
  </FileInputLabel>
</FileInput>

<input type="file" class="swan-file-input swan-visually-hidden" id="my-input" />
<label
  class="swan-file-input-label swan-button swan-button-skin-secondary"
  for="my-input"
  >Upload a file</label
>

<input type="file" class="swan-file-input swan-visually-hidden" id="my-input" />
<label
  class="swan-file-input-label swan-button swan-button-skin-secondary"
  for="my-input"
  >Upload a file</label
>

Inside of a Form

Since it is an input element, File Input can be used inside of a FormInputGroup along with a separate, external label and/or helper text. Helper text should display upload criteria such as accepted file formats and maximum file size.

<StandardForm>
  <FormField>
    <FormLabel>Form label</FormLabel>
    <FormInputGroup>
      <FileInput onChange={e => e.target.files[0]}>
        <FileInputLabel iconPosition="left">
          Upload from device
          <Icon iconType="upload" />
        </FileInputLabel>
      </FileInput>
      <FormHelper>
        Accepted file formats: JPG, JPEG, BMP, PNG, GIF, HEIC
      </FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Form label</FormLabel>
    <FormInputGroup>
      <FileInput onChange={e => e.target.files[0]}>
        <FileInputLabel iconPosition="left">
          Upload from device
          <Icon iconType="upload" />
        </FileInputLabel>
      </FileInput>
      <FormHelper>
        Accepted file formats: JPG, JPEG, BMP, PNG, GIF, HEIC
      </FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

Button variants

File Upload Label is a <label>, but it accepts many of the visual props from Button. You can use these to customize the appearance of the label.

Available props are skin, sizeVariant, size, widthVariant, width, specialVariant, iconPosition, and buttonShape.

<FlexBox flexWrap="wrap" gap="between-actions">
  <FileInput>
    <FileInputLabel iconPosition="left">
      Upload from device
      <Icon iconType="upload" />
    </FileInputLabel>
  </FileInput>
  <FileInput>
    <FileInputLabel skin="primary" iconPosition="left">
      Upload from device
      <Icon iconType="upload" />
    </FileInputLabel>
  </FileInput>
</FlexBox>

<FlexBox flexWrap="wrap" gap="between-actions">
  <FileInput>
    <FileInputLabel iconPosition="left">
      Upload from device
      <Icon iconType="upload" />
    </FileInputLabel>
  </FileInput>
  <FileInput>
    <FileInputLabel skin="primary" iconPosition="left">
      Upload from device
      <Icon iconType="upload" />
    </FileInputLabel>
  </FileInput>
</FlexBox>

Disabled

Use disabled when a File Input's action is unavailable.

<FileInput disabled>
  <FileInputLabel iconPosition="left">
    Upload from device
    <Icon iconType="upload" />
  </FileInputLabel>
</FileInput>

<FileInput disabled>
  <FileInputLabel iconPosition="left">
    Upload from device
    <Icon iconType="upload" />
  </FileInputLabel>
</FileInput>

File Upload pattern

File Input is part of a larger pattern of uploading files. The File Upload pattern ensures users are presented with a consistent UI regardless of the file types uploaded or the specific page navigated to.

For more information, see File Upload.

<GridContainer>
  <Row>
    <Column span={12}>
      <StandardForm>
        <GridContainer>
          <Row mb="between-subsections">
            <Column span={12}>
              <FormField>
                <FormInputGroup>
                  <FileDropzone
                    multiFileErrorMessage="Upload only one file"
                    aria-label="Dropzone"
                  >
                    <FileInput multiple>
                      <FileInputLabel iconPosition="left">
                        <Icon iconType="upload" /> Upload from device
                      </FileInputLabel>
                    </FileInput>
                  </FileDropzone>
                  <FormHelper>
                    Accepted file formats: JPG, JPEG, BMP, PNG, GIF, HEIC
                  </FormHelper>
                </FormInputGroup>
              </FormField>
            </Column>
          </Row>
          <Row verticalGap="matchGutter">
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile
                skin="loading"
                progressValue={40}
                fileName="my-file.png"
                fileDescription="3.56 MB"
              >
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/9x16.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/16x9.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
          </Row>
        </GridContainer>
      </StandardForm>
    </Column>
  </Row>
</GridContainer>

<GridContainer>
  <Row>
    <Column span={12}>
      <StandardForm>
        <GridContainer>
          <Row mb="between-subsections">
            <Column span={12}>
              <FormField>
                <FormInputGroup>
                  <FileDropzone
                    multiFileErrorMessage="Upload only one file"
                    aria-label="Dropzone"
                  >
                    <FileInput multiple>
                      <FileInputLabel iconPosition="left">
                        <Icon iconType="upload" /> Upload from device
                      </FileInputLabel>
                    </FileInput>
                  </FileDropzone>
                  <FormHelper>
                    Accepted file formats: JPG, JPEG, BMP, PNG, GIF, HEIC
                  </FormHelper>
                </FormInputGroup>
              </FormField>
            </Column>
          </Row>
          <Row verticalGap="matchGutter">
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile
                skin="loading"
                progressValue={40}
                fileName="my-file.png"
                fileDescription="3.56 MB"
              >
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/9x16.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/16x9.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
          </Row>
        </GridContainer>
      </StandardForm>
    </Column>
  </Row>
</GridContainer>

Props

See core props for additional props that can be applied to each of these components. Each component also accepts the React-equivalent native HTML attributes of the element it renders, unless a listed prop replaces one or a note says otherwise.

FileInput

Renders <input>. No props beyond core props and native HTML attributes.

FileInputLabel

Renders <label>.

prop	type	required	default	deprecation notes
`width` The width variation	`"standard""full-width"`⚠️ `"wide"null`	false	standard	Deprecated values: `wide`: Use default width or "full-width" for container-width buttons. Note: Neither option will exactly match the previous "wide" behavior.
⚠️ Deprecated `size` The size variation @deprecated This is deprecated without a replacement.	`"standard""mini"null`	false	standard	This is deprecated without a replacement.
`skin` The visual style of the Button	`"link""primary""secondary""unstyled""tertiary""clear-selection""destructive-primary""destructive-secondary""destructive-tertiary"null`	false	secondary
⚠️ Deprecated `specialVariant` Variations for special cases @deprecated This is deprecated without a replacement.	`"standard""design-path"null`	false	standard	This is deprecated without a replacement.
`iconPosition` The position of the icon in the Button	`"left""right"null`	false	null
⚠️ Deprecated `buttonShape` The shape of the Button - use `round` for icon buttons @deprecated Use `IconButton` component for creating icon-only buttons	`"standard""round"null`	false	standard	Use `IconButton` component for creating icon-only buttons

Button