Overview

#

Displays a grid of cards KCard.

KCardGrid provides base layouts for the most common grids in our ecosystem, as well as customization or complete override of the base layouts.

Together with KCard, it ensures accessible navigation within card lists, such as announcing only their titles when using the tab key to avoid overwhelming screen reader outputs.

Grid's visual behavior is based on the window breakpoint system . KCardGrid determines how many cards per row to display based on its layout and a current window breakpoint.

KCardGrid doesn't manage inner card content. This is KCard's responsibility.

Guidelines

#

• KCardGrid must be a direct parent of KCard ( KCard: KCard and KCardGrid )
• Avoid setting card widths. Rely on KCardGrid layouts and customization options ( Base layouts , Layout customization )
• Avoid setting card heights. Instead, set heights on card sections, use text truncation, or limit content in other ways ( Card height, content tolerance and alignment )
• Ensure robust content tolerance and consistent content alignment ( Card height, content tolerance and alignment )
• Preview cards on all screen sizes ( Fine-tuning responsiveness )
• Configure loading skeleton cards to match the expected visual output of cards with loaded data as closely as possible on all screen sizes ( Loading state )

Also follow KCard guidelines .

Usage

#

Base layouts

#

Three base layouts are available: '1-1-1', '1-2-2', and '1-2-3'. They determine the number of cards per row for each window breakpoint level .

'1-1-1' grid

#

Displays a grid with 1 card per row on every screen size. Show full definition

'1-2-2' grid

#

Displays a grid with 1 card per row on smaller screens, and 2 cards per row on medium and larger screens. Show full definition

'1-2-3' grid

#

Displays a grid with 1 card per row on smaller screens, 2 cards per row on medium screens, and 3 cards per row on larger screens. Show full definition

Layout customization

#

Base layouts can be customized or even completely overridden via the layoutOverride prop. layoutOverride takes an array of objects { breakpoints, cardsPerRow, columnGap, rowGap }, where:

• breakpoints is an array of 0-7 values corresponding to the window breakpoint levels . All other attributes in the same object take effect on these breakpoints.
• cardsPerRow overrides the number of cards per row for the specified breakpoints.
• columnGap/rowGap overrides grid column/row gaps for the specified breakpoints.

For example:

Here, the base 1-2-3 layout is partially overridden. Column and row gaps are decreased to 20px on breakpoints 0-1, and the number of cards per row is increased to 4 on breakpoints 4-7.

Card height, content tolerance and alignment

#

Cards displayed in KCardGrid stretch vertically to fit their content, making a grid row height match its tallest card.

Setting height on cards is discouraged. Instead, manage height bottom-up, for example by setting height on card sections, using text truncation, or other ways to limit its inner content. Such approaches ensure content tolerance, prevent unexpected overflows or excessive height, and keep vertical alignment of card sections consistent on a grid row. This is especially important when dealing with unknown lenghts or amounts of content displayed in cards. Consider:

Here, KCard has the following adjustments:

• Height is set on its aboveTitle slot content, and its preserveAboveTitle prop keeps the slot even without content. This results in consistent alignment of all cards' titles on a grid row.
• Similarly, height is set on its title slot, and the title is truncated.
• Its belowTitle slot's content is truncated.
• The number of pills in its footer slot is limited to a reasonable amount.

KCard offers other preserve... props corresponding to its slots.

Fine-tuning responsiveness

#

Grid configuration can be combined with KCard's settings to further improve responsive experience. A common pattern is switching KCard's horizontal orientation to vertical for smaller screens to organize content more effectively in limited space:

This technique also works for adjusting KCard slots content. In the following example, some metadata pills are hidden on smaller screens:

Loading state

#

While data is loading, KCardGrid shows loading skeleton cards. Use the loading prop to toggle the state. Note that KCardGrid internal optimizations may affect how closely the visual loading experience matches the loading value:

• The loading skeletons won't be displayed for short loading times (< 1s)
• When the loading skeletons are displayed, they will be visible for at least 1s

Use the buttons in the example below to preview.

Number of loading skeletons

#

By default, the number of loading skeletons corresponds to the number of cards in a single grid row if it were full. This behavior can be overridden via the count attribute (below), however do not override it unless indicated in the designs.

Loading skeletons configuration

Use the skeletonsConfig prop to configure skeleton cards to match the expected visual output of loaded cards on all screen sizes. Preview the layout and height of cards with loaded data and adjust skeletonsConfig accordingly.

skeletonsConfig takes an array of objects { breakpoints, count, height, orientation, thumbnailDisplay, thumbnailAlign }, where:

• breakpoints is an array of 0-7 values corresponding to the window breakpoint levels . All other attributes in the same object take effect on these breakpoints.
• count sets the number of skeleton cards for the specified breakpoints. See Number of loading skeletons .
• height sets the height of skeleton cards for the specified breakpoints.
• orientation sets the orientation of skeleton cards for the specified breakpoints. Corresponds to KCard's orientation .
• thumbnailDisplay sets the thumbnail display of skeleton cards for the specified breakpoints. Corresponds to KCard's thumbnailDisplay .
• thumbnailAlign sets the thumbnail alignment of skeleton cards for the specified breakpoints. Corresponds to KCard's thumbnailAlign .

For easier development, enable the debug prop to display the current breakpoint in the top left corner of the grid. Use the button in the example below to preview the debug mode.

Here, the height of loading skeleton cards is 400px with vertical orientation on breakpoints 0-3, and 220px with horizontal orientation on breakpoints 4-7. This makes skeleton cards resemble loaded cards at all breakpoints, creating a smooth transition for users during data loading. Note the bottom-up approach where we begin with a base setup for all breakpoints and gradually override on higher breakpoints. This simplifies the configuration object.

To get a sense of what skeleton layouts can be achieved, reload this page and the KCard page to preview the loading state in all examples.

Related

#

• KCard is a component for use within KCardGrid
• useKResponsiveWindow can be used to detect the current window breakpoint for fine-tuning responsiveness

Props

#

Slots

#