Overview

#

KCard is a versatile and accessible base component for creating various types of cards, such as lesson cards, resource cards, and more.

It manages the layout, including the thumbnail image, title, and other content. It offers several base layouts and many customization options. Cards like the examples shown can be created, and many others.

It is intended for use with KCardGrid. Below is an overview of KCard's features and best practices focused on its inner content. To learn more about card grids and related KCard features, see KCardGrid.

Guidelines

#

• Use KCard within KCardGrid as its direct child ( KCard and KCardGrid )
• Set a correct heading level ( Title )
• Ensure each card title is unique within a card grid ( Title )
• Do not use a heading element within the title slot
• Ensure content provided via slots is accessible ( Accessibility )
• Even if a thumbnail image is available, provide a placeholder element ( Placeholder )
• If using selection controls, use pre-defined labels ( Selection controls )
• Test final cards for semantic structure, accessibility, and right-to-left support ( Accessibility )

Also follow KCardGrid guidelines .

Usage

#

KCard and KCardGrid

#

KCard must always be used within KCardGrid as its direct child to ensure proper semantics and accessibility. Refer to KCardGrid to see how these components work together. Show more

            <template>
              <KCardGrid>
                <KCard />
              </KCardGrid>
            </template>
          

            <template>
              <div>
                <KCard />
              </div>
            </template>
          

            <KCardGrid>
              <MyCardComponent />
            </KCardGrid>
          

            <!-- MyCardComponent.vue -->
            <template>
              <KCard> ... </KCard>
            </template>
          

            <KCardGrid>
              <MyCardComponent />
            </KCardGrid>
          

            <!-- MyCardComponent.vue -->
            <template>
              <div>
                <KCard> ... </KCard>
              </div>
            </template>
          

Title

#

Always use the title prop to assign an unique title to each card in a grid, and the headingLevel prop to set the heading level on it. The level needs to correspond to the surrounding context. Show more

The scoped title slot with its titleText attribute can be used to customize the title.

Do not use a heading element within the title slot to avoid duplicate headings in the markup output.KCard already handles a heading element internally.Show more

            <template>
              <KCardGrid>
                <KCard
                  :headingLevel="3"
                  title="(1) Learn everything about hummingbirds"
                  ...
                >
                  <template #title="{ titleText }">
                    <h3>
                      <KLabeledIcon icon="readSolid">
                        <KTextTruncator
                          :text="titleText"
                          :maxLines="2"
                        />
                      </KLabeledIcon>
                    </h3>
                  </template>
                </KCard>
              </KCardGrid>
            </template>
          

The titleMaxLines prop can be used to truncate the title to a set number of lines.

Accessibility

#

KCard and KCardGrid offer built-in accessibility. For the parts they are responsible for, they manage proper semantics, screen reader support, and right-to-left language compatibility.

However, it is necessary to ensure that cards built with KCard are fully accessible, particularly the slot content that KCard doesn't control. Refer to Interactive elements for one such example.

Always test semantics, accessibility, and right-to-left of the final cards.

Click event and navigation

#

KCard's entire area is clickable.

You can use the to prop to navigate to a URL when the card is clicked.

      <KCardGrid ...>
        <KCard
          ...
          :to="{ name: 'NamedRoute' }"
        />
        <KCard
          ...
          :to="{ path: '/kcard' }"
        />
      </KCardGrid>
    

Listen to the click event to perform a custom action (whether or not the to prop is used).

      <KCardGrid ...>
        <KCard
          ...
          @click="onClick"
        />
        <KCard
          ...
          :to="{ path: '/kcard' }"
          @click="onClick"
        />
      </KCardGrid>
    

      export default {
        methods() {
          onClick() {
            console.log('Card clicked');
          }
        },
      };
    

Note that long clicks are ignored to allow for text selection.

See Interactive elements to learn how to disable card navigation in favor of a custom handler when elements like buttons are rendered within a card.

Layout

#

KCard has two orientations: horizontal and vertical. It is also possible to configure whether a thumbnail area is displayed, its size and alignment. By combining orientation, thumbnailDisplay and thumbnailAlign props, the following card layouts can be achieved to organize diverse kinds of content:

Responsiveness

#

To a large extent, KCardGrid takes care of responsiveness. Depending on a chosen card layout, KCard's inner area can be further adjusted to offer even better experience. Refer to KCardGrid: Fine-tuning responsiveness .

Content slots

#

Use aboveTitle, belowTitle, and footer slots to add content to a card. KCard will organize these areas according to its layout configuration . Apply custom styling to the inner content of slots to achieve desired effects.

The title slot is available as an alternative to the title prop. See Title .

Thumbnail

#

KCard offers multiple ways to display thumbnails, depending on these factors:

• The orientation prop decides if the thumbnail area appears above or beside other content.
• The thumbnailDisplay prop manages the thumbnail's visibility and size.
• The thumbnailAlignment prop sets which side the thumbnail appears on in horizontal orientation.

See Layout to see how these options can be combined to create different card layouts.

Placeholder

#

When KCard is set to display the thumbnail, the thumbnail area acts as a placeholder if the image is missing, fails to load, or is still loading. In such cases, a light gray background is shown in place of the image.

Use the thumbnailPlaceholder slot to add a placeholder element, such as an icon, to this area. Provide a placeholder element even if a thumbnail image is available. It serves as fallback content if the image fails to load unexpectedly.

See KImg placeholder for more examples, such as responsive placeholder icons.

Image scaling

#

The thumbnailScaleType prop determines how a thumbnail image is scaled to fit the thumbnail area. The available options are the same as KImg's scaling options.

If a thumbnail image's quality and ratio are unknown, which is often the case in our cards, it's best to use the default value 'centerInside' since it never distorts the image or impairs its quality.

See KImg's scaling guidance .

Interactive elements

#

When placing an interactive element, such as a button, inside a card using a slot, use the .stop event modifier on its @click handler. This prevents the card's own click event and navigation from being triggered. For router-link elements, apply @click.native.stop and @keyup.native.capture.stop to ensure that both mouse and keyboard interactions do not trigger the card's default click behavior.

This applies to all slot content, but considering accessibility is especially important with interactive elements. For instance, ariaLabel is applied to the bookmark icon button in the following example so that screenreaders can communicate its purpose. In production, more work would be needed to indicate the bookmark's toggled state. Always assess on a case-by-case basis.

In the example below, notice how using a router link allows users to Ctrl+click to open the link in a new tab.

Selection controls

#

Selection controls like checkboxes or radio buttons can be placed next to the card's main area via the select slot.

Use "Select '[card title]'" as label and hide it with the visuallyhidden class to keep the label available for screen readers.

KCard handles all remaining accessibility aspects, including semantics and focus order. If there are other interactive elements in a card, a selection control will receive focus last in the keyboard navigation order.

Managing the selection state is not KCard's responsibility.

Related

#

• KCardGrid is a component for use with KCard

Props

#

Events

#

Slots

#