ba-download

The ba-download component provides an intuitive way for users to download files

<ba-download filename="File Name" href="link/to/file.pdf" size="1MB"></ba-download>

The filename should be descriptive and concise. It should give the user a good idea of what they are downloading.

Show the file size (e.g. 2.5MB) as it helps users understand what they are downloading. For example they may choose to not download a large file if they are on a mobile data connection.

This helps users understand if thier device can support the format before they download the file

The file name is the name of the file once it's downloaded to their device. It would be odd if the file had the word download in the filename

This will help assistive technologies understand that how many downloads there are in a group without having to tab through them all

Disabled elements are not supported in BAgel. They are poor for accessibility and are sometimes not read properly by screen readers.

As an alternative, provide a message explaining why it’s unavailable or an alternative action that can be taken.

Element	State	Key press	Behaviour
Previous element in DOM	Previous element in DOM has focus	`Tab`	`<a>` in shadow DOM gets focus
`<a>` in shadow	a in shadow has focus	`Enter`	Triggers download and baClick event
`<a>` in shadow	a in shadow has focus	`Tab`	Next tabbable element in the DOM gets focus

Code

Properties & Attributes

Property	Attribute	Description	Type	Default
`filename`(required)	`filename`	The filename of the download. This will also be used for the downloaded file name.	`string`	`undefined`
`href`(required)	`href`	Link to the file / origin of the download	`string`	`undefined`
`loading`	`loading`	Show the loading state	`boolean \| undefined`	`false`
`size`	`size`	Size of the file e.g 1.2MB	`string \| undefined`	`undefined`
`type`	`type`	The file type e.g PDF	`string \| undefined`	`undefined`

Events

Event	Description	Type
`baClick`	Emitted when the internal element is clicked.	`CustomEvent<MouseEvent>`

Methods

`download() => Promise<void>`

Trigger the download of the file

Slots

Slot	Description	Permitted elements
Unnamed slot	Elements will render in the body of the component	None

Usage

Basic usage

Most scenarios will only require the filename, href and size attributes. Note the filename is used for the downloaded file name and the href is the link to the file

A simple download that links to a pdf file that saves to the users device as "File Name.pdf"

<ba-download filename="File Name" href="link/to/file.pdf" size="1MB"></ba-download>

Multiple downloads

Multiple downloads can be added to a page, when doing so a separator is added between each download

A group of downloads

<div role="list">
  <ba-download role="listitem" filename="File Name 1" href="link/to/file-1.pdf" size="1MB"></ba-download>
  <ba-download role="listitem" filename="File Name 2" href="link/to/file-2.pdf" size="1MB"></ba-download>
  <ba-download role="listitem" filename="File Name 3" href="link/to/file-3.pdf" size="1MB"></ba-download>
</div>

The download method can be called to trigger the download of the file. This is useful when the download needs to be triggered by a user action other than clicking the download button or to trigger the download after some other action has completed

Multiple downloads can be downloaded at the same time by clicking a download all button

<div role="list">
  <ba-download role="listitem" filename="File Name 1" href="link/to/file-1.pdf" size="1MB"></ba-download>
  <ba-download role="listitem" filename="File Name 2" href="link/to/file-2.pdf" size="1MB"></ba-download>
  <ba-download role="listitem" filename="File Name 3" href="link/to/file-3.pdf" size="1MB"></ba-download>
</div>

<button>Download All</button>

<script>
  const downloads = document.querySelectorAll('ba-download');
  const downloadAllButton = document.querySelector('button');

  downloadAllButton.addEventListener('baClick', () => {
    downloads.forEach(el => el.download());
  });
</script>

Show a loading state

When the loading attribute is added to ba-download the download text is replaced by a default "Preparing file" message. This is useful when the download needs to be prepared on the server before it can be downloaded

A download that is being prepared on the server

<ba-download filename="File Name" href="link/to/file.pdf" size="1MB" loading></ba-download>

The download method can be called to trigger the download of the file. This will remove loading state display text to the user to let them know the download has started

Triggering the download of a file that has finished being prepared on the server

  <ba-download filename="File Name" href="link/to/file.pdf" size="1MB" loading></ba-download>

  <script>
    const download = document.querySelector('ba-download');

    download.download()
  </script>