# Download Component of the SBB design system Lyne. - Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`) - Structure: main element with parts; use parts only within the element they belong to - Categories: Action - Status: Design guidelines complete ## Links - Page on digital.sbb.ch: https://digital.sbb.ch/en/design-system/lyne/components/download/ - Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-download--docs - Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/download/overview (API: https://lyne-angular.app.sbb.ch/angular/components/download/api) - GitHub: https://github.com/sbb-design-systems/lyne-components ## Elements - `sbb-download`: It displays a downloadable document, styled as a card. - `sbb-download-info`, only within `sbb-download`: It displays metadata of a document; used within a `sbb-download`. ## Overview ### What does the component do? A download displays a document for downloading, e.g. a PDF. The whole area is a link. Title, file type, size and modification date help users judge what they will get. ### When should the component be used? * To offer documents such as reports, forms or fact sheets for download. * To list several documents in a consistent way. ### Rules. * The title describes the content of the document, not the file name. * File type and size should always be shown, the modification date if it is relevant to users. * Documents that are not accessible must be marked as such. * For links to web pages, use a link or a card, not a download. ## Implementation (web components) The `` is a component that displays a downloadable document, styled as a [sbb-card](https://lyne-elements.app.sbb.ch/?path=/docs/elements-card--docs). The whole area is rendered as a link. ```html ``` The `label` shown as the title defaults to the file name extracted from the `href`, but can be set explicitly. ```html ``` ### Download vs. inline Whether the referenced document is downloaded or shown inline in the browser is up to the consumer: - With the `download` attribute, activating the component triggers the browser download. - Without it, the document is opened inline. In this case the link opens in a new browser tab (`target="_blank"`) by default and an "opens in new window" hint is provided to assistive technology. An explicitly set `target` takes precedence; an empty `target` attribute opts out of the new tab behavior without specifying a target. ```html ``` It's possible to set the other link related properties `rel` and `target` as well. ### Icon An icon is automatically derived from the `href` file extension. The following extensions are mapped to a dedicated document icon; any other (or missing) extension falls back to the generic `document-standard-small` icon. | File extension | Icon | | ------------------------------------------------ | ------------------------- | | `.pdf` | `document-pdf-small` | | `.xls`, `.xlsx` | `document-xls-small` | | `.ppt`, `.pptx` | `document-ppt-small` | | `.doc`, `.docx` | `document-doc-small` | | `.zip` | `document-zip-small` | | `.jpg`, `.jpeg`, `.png`, `.gif`, `.svg`, `.webp` | `document-image-small` | | _anything else / no extension_ | `document-standard-small` | A custom icon can be set with the `iconName` property or via the `icon` slot, which overrides the automatic derivation. ```html ``` ### Content The content of the unnamed slot and the `` block are both optional and independent. You can render custom content, a ``, both, or none of them. A `` placed in the unnamed slot is automatically moved to the dedicated `info` slot, so it always renders in the correct position. The `` assigns itself to the `info` slot in its `connectedCallback`, which only runs on the client; during server-side rendering the element stays in the unnamed slot until it is hydrated. ```html Custom description for the downloadable document. ``` ### Document metadata Use the optional `` component to display the document's metadata. The information is rendered in the order `type`, `size`, non-accessible, `changed`, skipping any value that has not been provided. - `type` falls back to the file extension of the parent `sbb-download`. - `size`, if it contains only digits, is interpreted as a number of bytes and shortened to the closest unit (e.g. `1234567` becomes `1 MB`); otherwise it is displayed as is. - `changed` accepts an ISO 8601 date string and is rendered as a formatted date. - `nonAccessible` renders a localized "not accessible" hint. ```html ``` ## API (web components) #### class: `SbbDownloadElement`, `sbb-download` ##### Properties | Name | Attribute | Privacy | Type | Default | Description | | ---------------------- | ----------------------- | ------- | ------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- | | `accessibilityCurrent` | `accessibility-current` | public | `string` | `''` | This will be forwarded as aria-current to the inner anchor element. | | `accessibilityLabel` | `accessibility-label` | public | `string` | `''` | This will be forwarded as aria-label to the inner anchor element. | | `color` | `color` | public | `'white' \| 'milk'` | `'white'` | Option to set the component's background color. | | `download` | `download` | public | `boolean` | `false` | Whether the browser will show the download dialog on click. | | `fileExtension` | - | public | `string` | | The lower-cased file extension extracted from the `href` (e.g. `pdf`), if any. | | `fileName` | - | public | `string` | | The file name extracted from the `href` (e.g. `report.pdf`). | | `href` | `href` | public | `string` | `''` | The href value you want to link to. | | `iconName` | `icon-name` | public | `string` | `''` | The icon name we want to use, choose from the small icon variants from the ui-icons category from here https://icons.app.sbb.ch. | | `label` | `label` | public | `string` | `''` | The label of the download. Defaults to the file name of the `href`. | | `rel` | `rel` | public | `string` | `''` | The relationship of the linked URL as space-separated link types. | | `target` | `target` | public | `'_blank' \| '_self' \| '_parent' \| '_top' \| string` | `''` | Where to display the linked URL. | ##### Slots | Name | Description | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | | Use the unnamed slot to add custom content. Optional. | | `icon` | Use this slot to display a custom icon, by providing a `sbb-icon` component. Optional. | | `info` | Slot used to render a `sbb-download-info`. A `sbb-download-info` placed in the unnamed slot is automatically moved to this slot. Optional. | #### class: `SbbDownloadInfoElement`, `sbb-download-info` ##### Properties | Name | Attribute | Privacy | Type | Default | Description | | --------------- | ---------------- | ------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `changed` | `changed` | public | `string` | `''` | The date of the latest change of the document, as an ISO 8601 string. | | `nonAccessible` | `non-accessible` | public | `boolean` | `false` | Whether the document is not accessible. | | `size` | `size` | public | `string` | `''` | The size of the document. If the value contains non-numeric characters it is rendered as is, otherwise it is interpreted as a number of bytes and shortened to the closest unit. | | `type` | `type` | public | `string` | `''` | The type of the document (e.g. `PDF`). Falls back to the extension of the parent `sbb-download`. |