# Composable card

Our [card component](https://elements.springernature.com/components/springernature/eds-c-card/) has several variants to help you highlight and promote content or services.

There may be some instances where you need a card variant that we do not provide. In this case, use the composable card to build what you need.

## Demo

{% demo 'A card', 'cardComposableWithImageDemo', demos.cardComposableDemo, component.brand %}

## When to use this component
Use the card to highlight and link to further content or services at points where it might be helpful to your users.

## When not to use this component
Use cards carefully. Too many cards can be overwhelming and mean that nothing is highlighted.

## How it works

### Installation

To install the components, [go to the get started guide for developers](https://github.com/springernature/elements).

To use the Composable card component, enter the following command in your Terminal:

```bash
npm install @springernature/elements
```

### Styles

Import the styles of the Composable card component into your `scss` file:

```scss
@import '../path/to/@springernature/elements/components/eds-c-card-composable';
```

### Options

| Name                 | Description                                                                                                           | Required |
|----------------------|-----------------------------------------------------------------------------------------------------------------------|:--------:|
| isFauxLink           | Makes the whole card into a link                                                                                    |          |
| isHighlight          | Adds the grey highlight line                                                                         |          |
| isHighlightAction    | Adds the blue highlight line for actionable cards                                                     |          |
| isHorizontal         | Enables responsive behaviour                                                                             |          |
| isMetadataHorizontal | Adds the table style, for example for journal metrics                                                      |          |
| iconURL              | Icon for the `eds-c-card-composable-with-icon` variant. Include path to and svg on the file system or an id in the svg sprite |          |
| metadata             | Defines the metadata displayed in the `eds-c-card-composable-with-metadata` and `eds-c-card-journal` variant           |          |
| cardLabel            | Defines the label for the card above the title for example ‘Article’ or ‘Review’                        |          |
| title                | Defines the title for the card                                                                                         |    ✅     |
| title.isSmall        | Enables smaller font for the title                                                                                     |          |
| title.text           | Defines the text for the card                                                                                          |    ✅     |
| title.headingLevel   | Defines the heading level                                                                                              |    ✅     |
| title.linkUrl        | Link for the card                                                                                                     |    ✅     |
| title.dataAttributes | Defines a list of data tracking attributes for the title                                                               |          |
| picture              | Defines the image for the card                                                                                         |          |
| image                | Defines the image for the card                                                                                         |          |
| truncateSummary      | Enables summary truncation                                                                                             |          |
| summary              | Defines summary text                                                                                                       |          |
| dataAttributes       | Defines a list of data attributes to the card                                                                          |          |
| srOnlyHighlightText  | Defines a descriptive label about the use of the highlight for screen reader users                                     |          |

### Variants
The card variants are:

- with image
- with icon
- with metadata
- journal card

#### with image
{% demo 'A card', 'cardComposableWithImageDemo', demos.cardComposableDemo, component.brand %}

#### with icon
{% demo 'A card', 'cardComposableWithIconDemo', demos.cardComposableDemo, component.brand %}

[Go to our guidelines on icons](https://elements.springernature.com/styleguide/springernature/icons/).

#### with metadata
To display metadata such as dates or content types alongside a title and description, set the `metadata` array. You can only have 2 unique metadata items in this array.

{% demo 'A card', 'cardComposableWithMetadataDemo', demos.cardComposableDemo, component.brand %}

#### journal card

{% demo 'A card', 'cardComposableDemo', demos.journalCardComposableDemo, component.brand %}

### Configuration
To view all the properties of this component, [go to the schema](https://github.com/springernature/elements/blob/main/components/eds-c-card-composable/data/eds-c-card-composable.schema.json).

Import the mixin for the responsive styles:

```scss
// consumer application level code
@import '../path/to/@springernature/elements/components/eds-c-card-composable'; // default styles
```

#### How to compose

{% demo 'A card', 'cardCompositionDemo', demos.journalCardComposableDemo, component.brand %}

Use `eds-c-card-composable` as a wrapper and pass the values and inject subcomponents as needed.

We provide 2 layouts. `eds-c-card-composable__container--with-sidebar` will keep the card horizontal on all screen sizes.

`eds-c-card-composable__container--to-sidebar` will stack on smaller screen sizes and switch to horizontal on larger screens.
For this to work, set the `isHorizontal` to `true`.

#### isHighlight
This is an optional property. If set to true, it will add a grey line to the card.

You can use this option to help a card stand out on a page. Or, if you have a long list of cards, you could add the line to each one as a way of marking out the list items.

On smaller screen sizes, the blue line will always be at the top of the card. If you are using the horizontal layout, then on larger screen sizes it will be on the left side of the card.

#### isHighlightAction
This is an optional property. If set to true, it will add a blue line to the card.

You can use this option to help a card stand out on a page. Or, if you have a long list of cards, you could add the line to each one as a way of marking out the list items.

On smaller screen sizes, the blue line will always be at the top of the card. If you are using the horizontal layout, then on larger screen sizes it will be on the left side of the card.

#### srOnlyHighlightText
This is an optional property that allows you to add a descriptive label about the use of the highlight for screen reader users. Use it to explain why a card is highlighted and give more meaning to screen reader users.

#### img or picture tag

Use `<img>` in simple cases like having a single image source.

Use `<picture>` for more complex cases such as responsive images.

#### image.aspectRatio or picture.aspectRatio
The aspect ratio for the image area is 16:9 and you should try to keep this aspect ratio for images. Where necessary, you can change this by using the `aspectRatio` property on the card’s image data.

```json
"aspectRatio": "4 / 3"
```

#### imageMimeType
Safari browser version 13 does not render webp images correctly even where there is a fallback image as jpeg.
Use the `imageMimeType` property to add the image type. This will add `imageMimeType: image/webpage”` and fix this issue.
If image `type` is not included, it will try to load the webp image format even though it is [not supported](https://caniuse.com/?search=webp).

#### truncateSummary

This is an optional property. If set to true, it will limit the summary text to 3 lines and then add an ellipsis.

You should keep summary text to under 150 characters and set this limit in your application. Where longer text is unavoidable, use this property.

Only use this property where you cannot control the length of the summary text.

#### cardLabel
This is an optional property. If set to true it will allow you to add a label above the title.

This label should be used to indicate content types, for example ‘Article’ or ‘Review’. Work with a content and/or UX designer to choose the correct labels.
