Skip to main content



Create a downloadable link for an asset.

ns-download creates the visual and semantics of the action of downloading an asset, as opposed to navigation. It can be used on its own or as a list of downloads for multiple files.

Content Guidance#


KeyField typeGuidelines
AFile descriptionProvide a description of what the file is and or contains.
BFile typeThe component will pick the file type from the file (if it isn't a format supported by the component, you need to provide a file type attribute).
CFile sizeAccurate file size in whichever unit that makes the most sense: B, kB, MB, GB.

Best practice#

๐Ÿ’š Do's๐Ÿ’” Don'ts
Use for all downloadsUse the instructions in the body e.g. 'download here'
Include file sizeDon't describe the file as a file
Describe what the file isUse as an inline element
Place in a list element with class download-list when you have more than 1 download link in rowMix them amongst text types of ns-cta.
Use it as a block element
Consider limiting the amount of downloads in a list to a manageable amount to ease choice

Considerations of best practice#

  • Include file size - this helps customers to make a decision on if they want to download it (available space, time to download).
  • File description - the text provided between the ns-download tags is used to create the filename for the downloaded file. This helps users identify the file that has been downloaded. Avoid adding any words you don't want to end up in the downloaded file's name.
  • Using it as a block element - if we were to include this component in a paragraph the icon would interrupt the flow of the text, making it less readable.
  • Lists - the download-list class can only be used on <ul> and <ol> html tags. Each ns-download must be a direct child of a <li>.
  • File type - if you are hitting an API to download the file, specifying the file type will be required even for supported formats.
  • File size - try and keep the file size to under maximum 3 digits. Example: instead of using "1498kB", use "1.5MB".


In order to comply with accessibility standards you should not force a file to open in a new tab. It must be left up to the user to decide whether to download a file, or open in a new tab.

The one exception to this rule is in forms as there are often challenges around losing the session of the journey when ns-download is used within ns-form; if the browser can display the file type it will open in a new tab.



View example on Storybook


View example on Storybook

Component placement#

The ns-download component can be used in the following components:


hrefhrefstringSuffixed by .pdf,.xlsThe url for the file to be downloaded (including file extension)
file-typefileTypestringpdf, xlsIf href doesn't have an extension, provide file type in this attribute.
file-sizefileSizestringUnits 'B','kB', 'MB', 'GB'The size of the file to be downloaded (including unit).

Specification notes#

  • File type - if the file's href attribute contains one of the following file extensions: .pdf, .xls, then the fileType attribute will have no effect.


  • Do you have insights or concerns to share? You can raise an issue via Github bugs.
  • See all the issues already raised via Github issues.

๐Ÿ’ฉ ๐ŸŽ‰ ๐Ÿฆ„ If you have any questions, contact us on Microsoft Teams in the Nucleus Design System channels.