ba-download
The ba-download component provides an intuitive way for users to download files
Airframe
Web Components
React
React Native
Anatomy
Icon
Helps users quickly identify the purpose of the component
Filename
Clearly indicates the name of the file being downloaded
File type (optional but recommended)
Provides users with information about the file format, helping them make informed decisions about downloading
File size (optional but recommended)
Provides users with information about the file size, helping them make informed decisions about downloading
Download button
A clear and accessible button that initiates the download process when clicked or activated via keyboard, with appropriate focus indicators and accessible labeling
Design Documentation
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 their 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
Live Demo
<ba-download filename="File Name" href="link/to/file.pdf" size="1MB"></ba-download>Properties and 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 |
Permitted ARIA roles
- listitem (when used in a list of downloads)
Slots
| Slot | Description | Permitted elements |
|---|---|---|
| Unnamed slot | Elements will render in the body of the component | None |
Parent components
ba-download can be slotted into:
Events
| Event | Description | Type |
|---|---|---|
baClick |
Emitted when the internal element is clicked. | CustomEvent<MouseEvent> |
Methods
| Method | Description | Type |
|---|---|---|
download() => Promise<void> |
Triggers the download of the file. | Promise<void> |
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
<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
<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>Triggering a download
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
<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>
<ba-button>Download All</ba-button>
<script>
const downloads = document.querySelectorAll('ba-download');
const downloadAllButton = document.querySelector('ba-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
<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
<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>Guidelines
This will help assistive technologies understand 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.
Keyboard navigation
State: Previous element in DOM has focus
<ba-download> gets focus
State: <ba-download> has focus
Triggers download and baClick event
Next tabbable element in the DOM gets focus
Usage and accessibility checklist
Use this checklist to confirm the component has been configured and used correctly.
UX checklist
- Filename is descriptive and concise, giving users a clear idea of the file contents
- Filename does not contain the word "download"
- Multiple downloads display a separator line between each item
- File size and type is displayed
- Loading state is shown with clear messaging (e.g. “Preparing file”) when the file is not immediately available.
- Download method is triggered at the appropriate time if initiated by another action (e.g. “Download All”).
Accessibility checklist
- For multiple downloads, role="list" is applied to the container and each ba-download has role="listitem"
- ba-download has not been disabled
- Focus indicator has not been obscured on all sides of the button
These checks are handled by the component and do not need to be repeated each time it is used.
- Displayed filename matches the name of the file when downloaded
- Loading state is announced to screen readers
- File type and size information is accessible to assistive technologies
- ba-download is operable using assistive technology
- Has a visible focus indicator on all sides of the button
- Colour contrast for all states in all BAgel themes
- Animations respect users' reduced motion settings
- High contrast mode adjustments