card replacement docs

2.21.1

Card

Sneak peak of the upcoming v3.0 Card component, (temporarily renamed as 'Card Replacement' on Bolt v2.x to avoid naming collisions).

Install via NPM
npm install @bolt/components-card-replacement

Description

Cards are shadowed containers that group together relevant and actionable information.

Best Practices

  • Placement should be in a manner where it is easily scannable
  • The headline should call out what the benefit is of clicking through
  • Avoid cluttering a card-replacement with too many calls to action
  • If the headline can work as link affordance without a button, don't have a button
  • If the headline does not clearly invoke action, use a CTA at the bottom of the card-replacement to entice the user
  // Standard card-replacement
{% include "@bolt-components-card-replacement/card-replacement.twig" with {
  media: {
    image: {
      src: "/images/placeholders/landscape-16x9-mountains.jpg",
      alt: "Image alt.",
    },
  },
  body: {
    eyebrow: "This is an eyebrow",
    headline: "This is a headline",
    paragraph: "This is a paragraph.",
  },
  actions: [
    {
      text: "This is a button",
      url: "https://pega.com",
    },
  ],
} only %}

// Custom section content
{% include "@bolt-components-card-replacement/card-replacement.twig" with {
  media: {
    content: "Pass custom content to the card-replacement media.",
  },
  body: {
    content: "Pass custom content to the card-replacement body.",
  },
} only %}

// Custom overall content
{% include "@bolt-components-card-replacement/card-replacement.twig" with {
  content: "Pass completely custom content to the card-replacement, without the styles of the card-replacement body.",
} only %}

Note: when assigning component props as HTML attributes on a web component, make sure to use kebab-case.

Prop Name Description Type Default Value Option(s)
attributes

A Drupal-style attributes object with extra attributes to append to this component.

object
tag

HTML tag that contains the card-replacement content.

string article
  • div, article, figure
horizontal

Displays the card media + body horizontally.

boolean
height

Controls the height of the card-replacement to auto fit to content or the full height of the column in a grid.

string full
  • auto or full
theme

Controls the theme of the individual card-replacement.

string none
  • xlight, light, dark, xdark, none
link

Providing a link will make the whole card-replacement clickable.

object
    • url

      Address for the link.

    • text

      Visually hidden text for link, included for accessibility.

    • attributes

      A Drupal-style attributes object with extra attributes to append to this component.

media

Media section of the card-replacement, accepts either image and video, or custom content.

object
    • image
      • @bolt-components-image/image.schema.yml > Object details
        • attributes

          A Drupal-style attributes object with extra attributes to append to this component.

          Type: object

        • src

          Source url for image.

          Type: string

        • alt

          Alt tag for image.

          Type: string

        • lazyload

          Lazyload can boost performance by loading images on demand, instead of on initial page load.

          Type: boolean

          • true or false
        • no_lazy

          Override the default lazyload behavior. Used only on the web component, where the presence of a boolean property always equates to true.

          Type: boolean

          • true or false
        • placeholder_color

          A valid CSS background color property shown while image loads.

          Type: string

        • placeholder_image

          Image path or image data shown while image loads.

          Type: string

        • srcset

          A comma seperated string of image urls and image widths, used for optimizing image loading performance.

          Type: string

        • sizes

          A list of one or more strings separated by commas indicating a set of source sizes. Each source size consists of a media condition (omitted for the last item), and a source size value. Learn more.

          Type: string

        • useAspectRatio

          Use the ratio prop instead.

          Type: boolean

          • true or false
        • ratio

          Set the aspect ratio for the image via slash-separated width and height values, e.g. 4/3. Currently required for aspect ratio to be applied properly. Set to "none" to opt out of aspect ratio.

          Type: string, boolean

        • max_width

          Set the max-width of the image as a valid CSS value, e.g. "300px" or "50%".

          Type: string

        • width

          Override the default width of the image. If no height is provided, aspect ratio will be maintained.

          Type:

        • height

          Override the default height of the image. If no width is provided, aspect ratio will be maintained.

          Type:

        • cover

          Set an image to fill its container.

          Type: boolean

          • true or false
        • imageAttributes

          A Drupal-style attributes object with extra attributes to append to this component.

          Type: object

        • valign

          Allows the image's vertical alignment behavior to be customized in certain situations (ex. background images). This can be configured via a pre-defined position (top | center | bottom) or via specific pixel or percent offset (ex. 30%).

          Type: string

        • align

          Allows the image's horizontal alignment behavior to be customized in certain situations (ex. background images). This can be configured via a pre-defined position (left | center | right) or via specific pixel or percent offset (ex. 30%).

          Type: string

    • video
      • @bolt-components-video/video.schema.yml > Object details
        • attributes

          A Drupal-style attributes object with extra attributes to append to this component.

          Type: object

        • videoId

          Brightcove ID for this video.

          Type: string, number

        • playerId

          Brightcover Player ID.

          Type: string

        • accountID

          ID of the Brightcove account that owns the video.

          Type: string, number

        • videoUuid

          A unique identifying string, randomly generated if not provided.

          Type: string

        • share_description

          A custom title to use in the share overlay

          Type: string

        • ratio

          Maintain video ratio.

          Type: boolean

        • collapsed

          Should the video be collapsed on load.

          Type: boolean

        • showMeta

          Should the video show meta data.

          Type: boolean

        • showMetaTitle

          Should the video show meta title.

          Type: boolean

        • controls

          Should the video controls be available.

          Type: boolean

        • autoplay

          Should the video auto-play on load.

          Type: boolean

        • loop

          Should the video loop.

          Type: boolean

        • on_init

          The on_init config allows for an external Javascript function inlined on the page to add any 3rd party scripts or video plugins to a <bolt-video> player instance when initializing. Please see the new recommended enabled_plugins and disabled_plugins options below.

          Type: string

        • default_plugins

          An array of the default <bolt-video> player plugins that are globally enabled by default.

          Type: array

          • playback
        • available_plugins

          The built-in <bolt-video> player plugins that are availble to be used in any player instance without requiring the use of any extra Javascript.

          Type: array

          • playback, social, email, cue
        • enabled_plugins

          Space-separated list of built-in <bolt-video> plugins for Brightcove to enable. Current include social, email, playback, and cue. For example: <bolt-video enabled-plugins="cue social email playback">.

          Type: string

        • disabled_plugins

          Space-separated list of any built-in <bolt-video> plugins for Brightcove to disable. Used to opt-out of any video plugins that are enabled by default (ex. the playback plugin). For example: <bolt-video disabled-plugins="playback">.

          Type: string

        • isBackgroundVideo

          Background video feature will be removed with Bolt v3.0

          Type:

    • content

      Passing free-form content into the card-replacement media will ignore image or video data. Use this if the pre-configured image or video doesn't satisfy your needs.

body

Body section of the card-replacement, accepts pre-configured eyebrow, headline, and paragraph or custom content.

object
    • eyebrow

      Regular eyebrow.

    • headline

      Headline pre-defined to size large.

    • paragraph

      Regular paragraph of text.

    • content

      Passing free-form content into the card-replacement body will ignore eyebrow, headline, and paragraph data. Use this if the pre-configured eyebrow, headline, and paragraph don't satisfy your needs.

actions

Actions section of the card-replacement, accepts buttons.

array
    • text
    • url
    • external
    • attributes

      A Drupal-style attributes object with extra attributes to append to this component.

content

Content will override media, body, and actions props. Use this to build a completely cuztomized card-replacement.

string , array , object
Open Accordion Close Accordion
raised

Manually switch on / off the raised (shadow + animation effect) treament. By default this config option is applied if the card-replacement contains a bolt-card-replacement-link OR includes the url prop.

boolean

Card - Basic Example

Image alt. Image alt.

This is an eyebrow

This is a headline

This is a paragraph.

This is a button

Card - Horizontal

Image alt. Image alt.

This is an eyebrow

This is a headline

This is a paragraph.

This is a button
Image alt. Image alt.

This is an eyebrow

This card's `action` is an internal link

This is a paragraph.

This is an internal button
Image alt. Image alt.

This is an eyebrow

This card's `action` is an external link

This is a paragraph.

This is an external button
Image alt. Image alt.

This is an eyebrow

This is a headline

This is a paragraph.

This is a button Verylongunbrokenword

Card - Theme Colors

Inside XDARK Parent Container

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

Inside DARK Parent Container

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

Inside LIGHT Parent Container

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

Inside XLIGHT Parent Container

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XLIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

LIGHT Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

DARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

XDARK Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

NONE Themed card-replacement

Each card-replacement can be individually theme, only when the theme is set to none should the card-replacement background be semi-transparent.

This is a button

Card - Height Options

Image alt. Image alt.

This card has auto height.

This is a button
Image alt. Image alt.

This card has full height. In pellentesque faucibus vestibulum. Nulla at nulla justo, eget luctus tortor. Nulla facilisi. Duis aliquet egestas purus in blandit. Curabitur vulputate, ligula lacinia scelerisque tempor, lacus lacus ornare ante, ac egestas est urna sit amet arcu. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie.

This is a button
Image alt. Image alt.

This card also has full height.

This is a button

Card - Video Example

Video

Video Meta Title Goes Here.

Anthem debuts its next-generation service desktop, driving frictionless customer experiences.

With link and video

This card has a link, which makes the whole card-replacement clickable, and you can make it play/pause the video. Action button is optional in this case.

Passing free-form content inside the card-replacement body only

A Rock Climber A Rock Climber

Anything can be passed inside the card body container. Woohoo!

Passing free-form content for the entire card

This is a button Verylongunbrokenword

This is an eyebrow

This is a headline

This is a paragraph.

This is a button Verylongunbrokenword

This is an eyebrow

This is a headline

This is a paragraph.


Anything can be passed inside the card container. Woohoo!
This card is completely customized using the content prop
Row 1 R1C1 R1C2 R1C3
Row 2 R2C1 R2C2 R2C3
Row 3 R3C1 R3C2 R3C3
Footer FC1 FC2 FC3
Image alt. Image alt.
Image alt. Image alt.

This is an eyebrow

This is a headline.

This is body text.

This is a button
Web Component Usage Bolt Text is a web component, you can simply use <bolt-card-replacement> in the markup to make it render. Its inner content is comprised of <bolt-card-replacement-media>, <bolt-card-replacement-body>, and <bolt-card-replacement-actions>.
This is an eyebrow This is a headline This is a paragraph. Internal link External link
<bolt-card-replacement> <bolt-card-replacement-media> <bolt-image src="/images/placeholders/landscape-16x9-mountains.jpg" alt="card-replacement media."></bolt-image> </bolt-card-replacement-media> <bolt-card-replacement-body> <bolt-text eyebrow>This is an eyebrow</bolt-text> <bolt-text headline>This is a headline</bolt-text> <bolt-text>This is a paragraph.</bolt-text> </bolt-card-replacement-body> <bolt-card-replacement-actions> <bolt-card-replacement-action url="https://pega.com"> Internal link </bolt-card-replacement-action> <bolt-card-replacement-action url="https://yahoo.com" external> External link </bolt-card-replacement-action> </bolt-card-replacement-actions> </bolt-card-replacement>
Simple Link Usage The simplest way to make the whole card-replacement clickable is by passing a link address to the url prop on the main <bolt-card-replacement> component itself. Also include the url-text prop for accessibility.
This is a card-replacement with an overall link that makes the whole card-replacement clickable.
<bolt-card-replacement url="https://google.com" url-text="Go to google.com"> <bolt-card-replacement-media> <bolt-image src="/images/placeholders/landscape-16x9-mountains.jpg" alt="card-replacement media."></bolt-image> </bolt-card-replacement-media> <bolt-card-replacement-body>This is a card-replacement with an overall link that makes the whole card-replacement clickable.</bolt-card-replacement-body> </bolt-card-replacement>
Advanced Link Usage Insert a <bolt-card-replacement-link> inside <bolt-card-replacement> and you can pass more than just url. <bolt-card-replacement-link> is similar to <bolt-link>. You can add custom attributes to <bolt-card-replacement-link> and insert a semantic <a> or <button> element inside.
Go to google.com This is a card-replacement with an overall link that makes the whole card-replacement clickable.
<bolt-card-replacement> <bolt-card-replacement-link custom-attribute="foo" html-attribute="bar"> <a href="http://google.com" target="_blank">Go to google.com</a> </bolt-card-replacement-link> <bolt-card-replacement-media> <bolt-image src="/images/placeholders/landscape-16x9-mountains.jpg" alt="card-replacement media."></bolt-image> </bolt-card-replacement-media> <bolt-card-replacement-body>This is a card-replacement with an overall link that makes the whole card-replacement clickable.</bolt-card-replacement-body> </bolt-card-replacement>
Nested Links While making the whole card-replacement clickable, you are still able to insert nested links as needed. Any <bolt-link>, <bolt-card-replacement-link>, and <bolt-card-replacement-action> will work as expected.
This is a card-replacement with an overall link that makes the whole card-replacement clickable, while the body can still have text links that would go somewhere else. Internal link External link
<bolt-card-replacement url="https://google.com"> <bolt-card-replacement-media> <bolt-ratio aspect-ratio-height="9" aspect-ratio-width="16"> <bolt-video data-setup='{"techOrder": ["Html5"], "resizeManager": false}' video-id="3861325118001" account-id="1900410236" show-meta show-meta-title player-id="r1CAdLzTW" controls></bolt-video> </bolt-ratio> </bolt-card-replacement-media> <bolt-card-replacement-body> This is a card-replacement with an overall link that makes the whole card-replacement clickable, while the body can still have <bolt-link target="_blank" url="https://boltdesignsystem.com/docs">text links</bolt-link> that would go somewhere else. </bolt-card-replacement-body> <bolt-card-replacement-actions> <bolt-card-replacement-action url="https://pega.com"> Internal link </bolt-card-replacement-action> <bolt-card-replacement-action url="https://yahoo.com" external> External link </bolt-card-replacement-action> </bolt-card-replacement-actions> </bolt-card-replacement>
Debug Panel