Card

Description

Cards contain content and actions related to a single subject. They help to organize content and increase scannability.

See live demos on storybook

Storybook Card Demos

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-card @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:

npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

Usage

A Card is used to separate information into smaller subjects, or topics, within larger components. Components, such as Expansion Panel and Table, utilize Cards or features similar to them. For example, an Expansion Panel can include multiple List items or Cards and a Table implements a header section similar to the Card component.

Sub Components

Cards are composed of the following sub components:

| Name | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Card | Primary container for card sub components | | CardActions | Container for actionable buttons and icon buttons. It is most commonly placed at the bottom of the card | | CardActionButton | Button button specially formatted for Element Card. | | CardActionIcon | Icon Button button specially formatted for Element Card. | | CardBody | Card Body is the main card body. It can either be content or composed of other Element components. | | CardContent | Card Content contains the semantic content of the card. Non-semantic elements, ie an overlay layer, to a card should live outside this div. Should not be used with Card Media | | CardDivider | Divider used to separate components of card. Can add a color variant for brand expression. | | CardFilter | Container for filtering controls, typically placed directly above filtered content | | CardMedia | Card Media is for holding a larger, attention grabbing images. Optionally, additional child content may be overlaid on the image. | | CardPrimaryAction | Card Primary Action is a wrapper component to make all it's children a primary action. | | CardTitle | Container for titles, headings and other larger typography, typically placed at the top of the card, but can be placed anywhere, ie, as an overlay in Card Media. |

Card Props

| Name | Type | Default | Required | Description | | ------------- | ------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bodyAlignment | string | 'left-top' | false | Alignment of the Card Body.Accepted Values: left-center, left-top, left-bottom, centered, right-center, right-top, right-bottom | | height | string | 'auto' | false | Height style property of card. | | loadingCard | boolean | false | false | If true the card will be styled for a loading spinner | | style | object | null | false | Passthrough style object. | | themeColor | string | 'surface' | false | Background color of the card. It is recommended to set to transparent if setting theme color on the Card Title or Card Body.Accepted Values: transparent, surface, surface-variant, primary, primary-variant, primary-50, primary-100, primary-200, primary-300, primary-400, primary-500, primary-600, primary-700, primary-800, primary-900, secondary, secondary-variant, secondary-50, secondary-100, secondary-200, secondary-300, secondary-400, secondary-500, secondary-600, secondary-700, secondary-800, secondary-900, danger, danger-variant, danger-50, danger-100, danger-200, danger-300, danger-400, danger-500, danger-600, danger-700, danger-800, danger-900, ancillary-100, ancillary-200, ancillary-300, ancillary-400, ancillary-500, ancillary-600, ancillary-700, ancillary-800, ancillary-900 | | variant | string | 'default' | false | Variant options include default (set by theme), flat, outlined, and raised. The flat variant removes elevation. The outlined variant adds border and removes elevation. The raised variant adds elevation.Accepted Values: default, flat, outlined, raised |

Card Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Content to be rendered inside the Card. Should be one of CardActions, CardBody, CardContent, CardDivider, CardFilter, CardMedia, or CardTitle. |

Card Breaking Changes

| Description | | ----------------------------------------------------- | | outlined (removed): Use variant="outlined" instead. |

Card Action Button Props

| Name | Type | Default | Required | Description | | ---------------------- | ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | actionButtonThemeColor | string | 'primary' | false | Override the default (primary) color with the secondary color. Most commonly used when the control is placed on a darker surface.Accepted Values: primary, secondary | | className | string | undefined | false | The css class name to be passed through to the component markup. | | customRef | reference | undefined | false | Reference to the DOM button. This enables a greater level of integration. | | disabled | boolean | false | false | Prevent the user from interacting with the component. | | fullWidth | boolean | false | false | Applies a full-width style where the button will fill it's container. | | href | string | null | false | The button will render as an anchor tag. | | label | string | null | false | The displayed text. Expects a valid string. If label and children are both set, label will take priority. | | leadingIcon | string|React.ReactNode | null | false | Adds the given Icon to the left of the button text. May not be used with trailingIcon - if leadingIcon and trailingIcon are both set, leadingIcon will take priority. Expects the name of a valid Material.io icon, however an icon component may be passed in instead for more control, | | trailingIcon | string|React.ReactNode | null | false | Adds the given Icon to the right of the button text. May not be used with leadingIcon - if leadingIcon and trailingIcon are both set, leadingIcon will take priority. Expects the name of a valid Material.io icon, however an icon component may be passed in instead for more control. | | type | string | 'button' | false | This applies the html button type (button, submit, reset) or the anchor media type when used with the href property.Accepted Values: button, submit, reset |

Card Action Button Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Content to be rendered inside the button. Can be used instead label of to provide more flexibility. Accepts any valid markup. Warning, if Label is set, it will be used instead of child content. |

Card Action Button Events

| Name | Default | Required | Params | Description | | ------- | --------- | -------- | ------ | ----------------------------------------- | | onClick | undefined | false | | The primary interaction event for button. |

Card Action Icon Props

| Name | Type | Default | Required | Description | | ----------------------- | ------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | active | boolean | false | false | Programmatically sets the toggle state of the button when used as a toggle button. If not set, the toggle state will be managed internally. | | ariaLabel | string | null | false | Accessibility label for assistive technologies. | | ariaLabelledBy | string | null | false | Id of the component being labeled for assistive technologies. | | className | string | undefined | false | The css class name to be passed through to the component markup. | | disabled | boolean | false | false | Disables the icon button. | | toggleOffAriaLabel | string | null | false | The aria-label value to be read by a screen-reader when the button is toggled off. Example 'Add to Favorites'. Alternatively, toggleOffAriaLabelledBy may be used instead. | | toggleOffAriaLabelledBy | string | null | false | The aria-labelledbyvalue when the button is toggled on. This should be the id of a parent element to be read by a screen reader instead of aria-label. | | toggleOnAriaLabel | string | null | false | The aria-label value to be read by a screen-reader when the button is toggled on. Example 'Remove from Favorites'. Alternatively, toggleOnAriaLabelledBy may be used instead. | | toggleOnAriaLabelledBy | string | null | false | The aria-labelledbyvalue when the button is toggled on. This should be the id of a parent element to be read by a screen reader instead of aria-label. | | variant | string | empty string | false | Variants prefixed with filled- will add a background color to the icon according to the theme. Variants prefixed with color- will change the color of the icon according to the theme.Accepted Values: filled-danger-alt, filled-danger, filled-primary, filled-secondary, color-primary, color-secondary, color-on-darkDeprecated Values: primary-alt, secondary-alt, primary, danger-alt, danger |

Card Action Icon Render Props

| Name | Type | Default | Required | Description | | --------- | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | The content when when using the Card Action Icon Button normally. Expects a string, but a valid custom icon is accepted. For toggle button functionality, use toggleOn and toggleOff instead. | | toggleOff | React.ReactNode | null | false | The content to be rendered when the Card Action Icon Button is toggled off. Expects a string, but a valid custom icon is accepted. The typical use case for a toggle button would be to set an Icon for toggleOn and toggleOff, leaving children blank. | | toggleOn | React.ReactNode | null | false | The content to be rendered when the Card Action Icon Button is toggled on. Expects a string, but a valid custom icon is accepted. The typical use case for a toggle button would be to set an Icon for toggleOn and toggleOff, leaving children blank. |

Card Action Icon Events

| Name | Default | Required | Params | Description | | ------- | --------- | -------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | onClick | undefined | false | 1. Name: event, Type: event, Description: The javascript event | Fired when the user clicks the Card Action Icon Button, will return toggle state, if applicable. |

Card Actions Props

| Name | Type | Default | Required | Description | | --------- | ------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | alignment | string | 'leading' | false | Aligns action buttons and icon buttons. 'center' and 'trailing' only allow buttons.Accepted Values: leading, center, trailing |

Card Actions Render Props

| Name | Type | Default | Required | Description | | ------------- | --------------- | ------- | -------- | ---------------------------- | | actionButtons | React.ReactNode | null | false | Add buttons to card actions. | | actionIcons | React.ReactNode | null | false | Add icons to card actions. |

Card Actions Breaking Changes

| Description | | --------------------------------------------------- | | children (removed): No longer needed | | footerAlignLeft (removed): See alignment="leading". | | withOverflow (removed): No longer needed. |

Card Body Props

| Name | Type | Default | Required | Description | | -------------- | ------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | themeColor | string | 'surface' | false | Background color of the card body. It is recommended to set to the Card themeColor to transparent if setting the Card Body color.Accepted Values: surface, surface-variant, primary, primary-variant, primary-50, primary-100, primary-200, primary-300, primary-400, primary-500, primary-600, primary-700, primary-800, primary-900, secondary, secondary-variant, secondary-50, secondary-100, secondary-200, secondary-300, secondary-400, secondary-500, secondary-600, secondary-700, secondary-800, secondary-900, danger, danger-variant, danger-50, danger-100, danger-200, danger-300, danger-400, danger-500, danger-600, danger-700, danger-800, danger-900, ancillary-100, ancillary-200, ancillary-300, ancillary-400, ancillary-500, ancillary-600, ancillary-700, ancillary-800, ancillary-900 | | typographyType | string | 'body2' | false | Sets typography class for Card Body. This can be overwritten by the children markupAccepted Values: body1, body2, button, caption, display1, display2, display3, display4, display5, display6, overline, subtitle1, subtitle2Deprecated Values: headline1, headline2, headline3, headline4, headline5, headline6 |

Card Body Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ------------------------------------------------------------------------ | | children | React.ReactNode | null | false | Content to be rendered inside the title block. Accepts any valid markup. |

Card Content Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | -------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Content to be rendered inside the content block. Accepts any valid markup. |

Card Content Breaking Changes

| Description | | -------------------------------------------- | | height (removed): No longer needed. | | horizontalAlign (removed): No longer needed. | | primaryAction (removed): No longer needed. | | verticalAlign (removed): No longer needed. |

Card Divider Props

| Name | Type | Default | Required | Description | | ----------------- | ------ | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dividerThemeColor | string | 'on-surface-stroke' | false | Theme color for the Card Divider. Leave empty for gray.Accepted Values: null, on-surface-stroke, primary, primary-variant, primary-50, primary-100, primary-200, primary-300, primary-400, primary-500, primary-600, primary-700, primary-800, primary-900, secondary, secondary-variant, secondary-50, secondary-100, secondary-200, secondary-300, secondary-400, secondary-500, secondary-600, secondary-700, secondary-800, secondary-900, danger, danger-variant, danger-50, danger-100, danger-200, danger-300, danger-400, danger-500, danger-600, danger-700, danger-800, danger-900, ancillary-100, ancillary-200, ancillary-300, ancillary-400 | | dividerVariant | string | 'dense' | false | Choose between dense and tall variants.Accepted Values: dense, tall |

Card Filter Props

| Name | Type | Default | Required | Description | | ---------- | ------ | --------- | -------- | ------------------------------------------------------------------------------ | | className | string | undefined | false | The css class name to be passed through to the component markup. | | filterType | string | 'tabs' | false | Type of filter being used.Accepted Values: tabs, chips, select, select-2 |

Card Filter Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Content to be rendered inside the title block. Mostly commonly a Select, Textfield component, however any valid components or markup may be used. |

Card Horizontal Group Props

| Name | Type | Default | Required | Description | | --------- | ------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------- | | className | string | undefined | false | The css class name to be passed through to the component markup. | | rtl | boolean | false | false | Changes which side of content the Card side media renders on. Improves layout for right-to-left languages. |

Card Horizontal Group Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | --------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Most commonly text or a Typography component, but accepts any valid markup. |

Card Leading Media Props

| Name | Type | Default | Required | Description | | -------- | -------------- | -------- | -------- | -------------------------------------------------------------------------- | | mediaUrl | string | null | false | Url for Card media | | ratio | string | 'square' | false | Applies aspect ratio style to the card media.Accepted Values: square | | width | number|string | '30%' | false | Width for Card media |

Card Media Props

| Name | Type | Default | Required | Description | | ----------------- | ------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contentPlacement | string | 'bottom' | false | Adjust placement of the media content.Accepted Values: bottom, top | | imageUrl | string | null | false | Image Url for card background image | | overlay | boolean | false | false | Adds an overlay over to the Card Media. | | overlayThemeColor | string | 'dark' | false | Overlay theme color.Accepted Values: dark, light, surface, linear-gradient-white-to-bottom, linear-gradient-white-to-top, linear-gradient-black-to-bottom, linear-gradient-black-to-top, linear-gradient-primary-dark-to-bottom, linear-gradient-primary-dark-to-top, linear-gradient-primary-darker-to-bottom, linear-gradient-primary-darker-to-top, linear-gradient-primary-to-bottom, linear-gradient-primary-to-top, linear-gradient-secondary-dark-to-bottom, linear-gradient-secondary-dark-to-top, linear-gradient-secondary-darker-to-bottom, linear-gradient-secondary-darker-to-top, linear-gradient-secondary-to-bottom, linear-gradient-secondary-to-top | | ratio | string | 'square' | false | Applies aspect ratio style to the card media.Accepted Values: square, sixteen-nine, four-three, four-five, two-one |

Card Media Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Child components will be rendered on top of the provided image. Use contentBottom and contentTop to control content positioning. Accepts any valid markup. |

Card Media Breaking Changes

| Description | | -------------------------------------------------------------- | | contentBottom (removed): see contentPlacement="top" instead. | | contentTop (removed): see contentPlacement="bottom" instead. | | sixteenNine (removed): see ratio="sixteen-nine" instead. | | square (removed): see ratio="square" instead. |

Card Overlay Props

| Name | Type | Default | Required | Description | | ----------------- | ------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | className | string | undefined | false | The css class name to be passed through to the component markup. | | overlayThemeColor | string | 'dark' | false | Overlay theme color.Accepted Values: dark, light, surface, linear-gradient-white-to-bottom, linear-gradient-white-to-top, linear-gradient-black-to-bottom, linear-gradient-black-to-top, linear-gradient-primary-dark-to-bottom, linear-gradient-primary-dark-to-top, linear-gradient-primary-darker-to-bottom, linear-gradient-primary-darker-to-top, linear-gradient-primary-to-bottom, linear-gradient-primary-to-top, linear-gradient-secondary-dark-to-bottom, linear-gradient-secondary-dark-to-top, linear-gradient-secondary-darker-to-bottom, linear-gradient-secondary-darker-to-top, linear-gradient-secondary-to-bottom, linear-gradient-secondary-to-top | | position | string | 'full' | false | Position of the Overlay. Use overlayThemeColor to change the theme color. If set to leading or trailing be sure to set alignment on Card accordingly to have Card Content over the overlay.Accepted Values: full, leading, trailing |

Card Overlay Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Content to be rendered inside the Card Overlay. Useful for angles or other non semantic elements displayed in the Card. |

Card Primary Action Props

| Name | Type | Default | Required | Description | | ---- | ------------------------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | tag | string|React.ElementType|React.Component | 'div' | false | By default a div will be rendered, this allows another tag/component to be used instead. A block type element/component is suggested. |

Card Primary Action Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | --------------------------------------------- | | children | React.ReactNode | null | false | Content to be rendered as the primary action. |

Card Primary Action Events

| Name | Default | Required | Params | Description | | ------- | --------- | -------- | ------ | --------------------------------------- | | onClick | undefined | false | | The primary interaction event for card. |

Card Title Props

| Name | Type | Default | Required | Description | | ----------------- | ------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | className | string | undefined | false | The css class name to be passed through to the component markup. | | leadingBlockType | string | empty string | false | The type of media that will render in the leading block. See README for size constraints.Accepted Values: avatar, icon, icon-with-background, thumbnail | | placement | string | 'top' | false | Where title appears in card.Accepted Values: top, middle, bottom | | stacked | boolean | false | false | Prop that makes card title stackable. | | themeColor | string | 'surface' | false | Background color of the CardTitle.Accepted Values: surface, primary, secondary | | trailingBlockType | string | empty string | false | The type of media that will render in the trailing block. See README for size constraints.Accepted Values: title-actions, avatar, badge, icon, icon-with-background, thumbnail |

Card Title Render Props

| Name | Type | Default | Required | Description | | -------------------- | --------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | leadingBlock | React.ReactNode | null | false | Content to be displayed in the leading block container. See README for types supported. | | overlineText | React.ReactNode | null | false | Content to be displayed in the Overline text of the title. Expects a string, but can be any valid markup. | | primaryText | React.ReactNode | null | false | Content to be displayed in the Primary text of the title. Expects a string, but can be any valid markup. | | secondaryText | React.ReactNode | null | false | Content to be displayed in the Secondary text of the title. Expects a string, but can be any valid markup. | | stackedSecondaryText | React.ReactNode | null | false | Content to be displayed in the Secondary text of the title and could be used to make Card title stackable. Expects a string, but can be any valid markup. | | trailingBlock | React.ReactNode | null | false | Content to be displayed in the trailing block container. See README for types supported. |

Card Title Breaking Changes

| Description | | --------------------------------------------------------------------------- | | children (removed): Use the content props/slots to populate the Card Title. | | height (removed): No longer needed. | | large (removed): no longer needed | | titleBigText (removed): See trailingBlock and TypoDisplay. | | titleFilters (removed): See trailingBlock. | | titleIcons (removed): See trailingBlock and trailingBlockType=icon. | | withOverflow (removed): No longer needed. |