KCard link to current page

develop | Release notes

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.

✔ Do
Always use KCardGrid, even for a single card 

            <template>
              <KCardGrid>
                <KCard />
              </KCardGrid>
            </template>
✘ Don't
Not use KCardGrid 

            <template>
              <div>
                <KCard />
              </div>
            </template>
✔ Do
Make KCard a direct child of KCardGrid 

            <KCardGrid>
              <MyCardComponent />
            </KCardGrid>
          

            <!-- MyCardComponent.vue -->
            <template>
              <KCard> ... </KCard>
            </template>
✘ Don't
Build cards in such a way
that KCard is not a direct child of KCardGrid 

            <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.

Examples:

  • If a page with cards has an h1 and no subsections, set headingLevel to 2 to render card titles as h2.
  • If there's an h2 subsection with cards, set headingLevel to 3 to render card titles as h3.

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


      <template>
        <KCardGrid>
          <KCard
            :headingLevel="3"
            title="(1) Learn everything about hummingbirds: their habitats, feeding patterns, and stunning flight abilities"
            ...
          >
            <template #title="{ titleText }">
              <KLabeledIcon icon="readSolid">
                <KTextTruncator
                  :text="titleText"
                  :maxLines="1"
                />
              </KLabeledIcon>
            </template>
          </KCard>
        </KCardGrid>
      </template>

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.

✘ Don't

            <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: 


      <KCardGrid ...>
        <KCard
          ...
          orientation="vertical"
          thumbnailDisplay="large"
        />
        <KCard
          ...
          orientation="vertical"
          thumbnailDisplay="large"
        />
        <KCard
          ...
          orientation="vertical"
          thumbnailDisplay="small"
        />
      </KCardGrid>

      <KCardGrid ...>
        <KCard
          ...
          orientation="horizontal"
          thumbnailDisplay="large"
          thumbnailAlign="left"
        />
        <KCard
          ...
          orientation="horizontal"
          thumbnailDisplay="small"
          thumbnailAlign="right"
        />
      </KCardGrid>

      <KCardGrid ...>
        <KCard
          ...
          v-for="i in 3"
          orientation="vertical"
          thumbnailDisplay="none"
        />
      </KCardGrid>

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. 


      <KCardGrid ...>
        <KCard ...>
          <template #aboveTitle>
            <KLabeledIcon
              icon="readSolid"
              label="Read"
            />
          </template>
          <template #belowTitle>
            <KTextTruncator
              text="Discover how hummingbirds play a big role in nature despite their small size. Find out more about their beauty, how they help plants grow, and where they live."
              :maxLines="5"
            />
          </template>
          <template #footer>
            <span :style="{ ... }">Short Activity</span>
            <span :style="{ ... }">Biology</span>
          </template>
        </KCard>
      </KCardGrid>

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. 


      <KCardGrid ...>
        <KCard ...>
          <template #thumbnailPlaceholder>
            <KIcon
              :style="{ fontSize: '48px' }"
              icon="readSolid"
            />
          </template>
        </KCard>
      </KCardGrid>

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 adding interactive elements like buttons to a card via slots, apply the .stop event modifier to their @click event to prevent the card click event and navigation .

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. 


      <KCardGrid ...>
        <KCard ...>
          <template #footer>
            <KIconButton
              ariaLabel="Bookmark resource"
              :icon="isBookmarked ? 'bookmark' : 'bookmarkEmpty'"
              @click.stop="isBookmarked = !isBookmarked"
            />
          </template>
        </KCard>
      </KCardGrid>

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.


      <KCardGrid ...>
        <KCard ...>
          <template #select>
            <KCheckbox
              :checked="..."
              @change="..."
            >
              <span class="visuallyhidden">Select 'First card'</span>
            </KCheckbox>
          </template>
        </KCard>

        <KCard ...>
          <template #select>
            <KCheckbox
              :checked="..."
              @change="..."
            >
              <span class="visuallyhidden">Select 'Second card'</span>
            </KCheckbox>
          </template>
        </KCard>
      </KCardGrid>

Related
#

Props
#

Name Description Type Default Required
headingLevel
#
HTML heading level in range (h2 - h6) for the title
 number — true
to
#
A Vue route object. If provided, card click will navigate to the target.
 object null —
title
#
Card title
 string null true
titleMaxLines
#
Truncates title lines
 number 2 —
orientation
#
Controls card orientation. Options: 'horizontal', 'vertical'.
 string 'horizontal' —
thumbnailDisplay
#
Controls if and how the thumbnail appears in the card. Options: 'none', 'small', or 'large'.
 string 'none' —
thumbnailSrc
#
Thumbnail source path.
 string null —
thumbnailScaleType
#
Specifies how the thumbnail scales in the card. Options: 'centerInside', 'contain', 'fitXY'.
 string 'centerInside' —
thumbnailAlign
#
Controls the alignment of the thumbnail area in horizontal card orientation. Options: 'left', 'right'
 string 'left' —
preserveAboveTitle
#
If aboveTitle slot is empty, controls whether its space is preserved or not.
 boolean false —
preserveBelowTitle
#
If belowTitle slot is empty, controls whether its space is preserved or not.
 boolean false —
preserveFooter
#
If footer slot is empty, controls whether its space is preserved or not.
 boolean false —
isSkeleton
#
Private. Do not use.
 boolean false —

Events
#

Name Description
click
#
Emitted when a card is clicked or pressed with enter. Contains the DOM event in the payload.
focus
#
Emitted when a card gets focus
hover
#
Emitted when a card is hovered

Slots
#

Name Description
title
#
A scoped slot via which the title can be customized.
aboveTitle
#
Places content to the area above the title.
belowTitle
#
Places content to the area below the title.
thumbnailPlaceholder
#
Places content to the thumbnail placeholder area.
footer
#
Places content to the footer area.
select
#
For selection controls such as checkbox or radio button