The FilterableCardGrid component renders a list of items as cards with a
searchbox above the grid. Typing into the searchbox filters the visible cards
live by matching against the item’s title, description, tags, and badges. It is
designed as a drop-in replacement for CardGrid + Card on collection listing
pages.
Each item can carry two kinds of metadata beyond its title and description:
tags are searchable but invisible, while badges are short labels (e.g.
"Week 1") rendered as small chips between the title and description, and
searched like everything else.
An item can also carry an image (an imported image only — unlike Card,
there is no RemoteImage form) with optional imageAlt, rendered above the
title in the same frame Card uses. The image is not searched. Where a grid
runs to many images, narrow imageWidths from its default [320, 640, 960]:
every width is a build-time encode per card.
---
import FilterableCardGrid from "astro-theme-university/components/FilterableCardGrid.astro";
const items = [
{
title: "Installation",
href: "/install/",
description: "Get up and running in minutes.",
},
{
title: "Configuration",
href: "/config/",
description: "Customise the theme to suit your site.",
},
{
title: "Deployment",
href: "/deploy/",
description: "Publish your site to the web.",
},
];
---
<FilterableCardGrid {items} columns={2} label="Filter docs" />
Props#
| Prop | Type | Default | Description |
|---|---|---|---|
items * | CardItem[] | --- | Items to render and filter. |
columns | 2 | 3 | 3 | Number of columns in the grid. |
label | string | "Filter items" | Accessible label for the search input. |
placeholder | string | "Filter…" | Placeholder text for the search input. |
emptyMessage | string | "No items match" | Message shown when the query matches no items. |
headingLevel | HeadingLevel | "h3" | Heading level for card titles. |
id | string | --- | Optional stable id when more than one otherwise-identical grid appears on a page. |
imageWidths | number[] | [320, 640, 960] | Srcset widths (px) for card images, as `Card`'s `imageWidths`. The default covers the card grids up to 2x DPR; a grid of many images is worth narrowing, since every width is a build-time encode per card. |
imageSizes | string | "(min-width: 48rem) 24rem, 100vw" | The `sizes` attribute paired with `imageWidths`. |
imageFormat | ImageOutputFormat | themeImageFormat | Output format for card images. Defaults to the `imageFormat` integration option. |
Examples#
With summaries and tags
Keyboard shortcuts#
- / — focus the searchbox from anywhere on the page (ignored when typing in another input)
- Escape — clear the searchbox while it is focused
Filter behaviour#
The query is split on whitespace into tokens. Every token must appear (substring match, case-insensitive) somewhere in the item’s title, description, tags, or badges. With no query, all items are shown in their original order.
Accessibility#
- The searchbox uses
type="search"with the suppliedlabelas itsaria-label. - A live region announces the current match count whenever the query changes.
- The keyboard hint (
<kbd>/</kbd>) is markedaria-hidden. - Cards remain regular
<a>elements — focus order, hover states, and link behaviour match the standardCardcomponent.
Notes#
The component server-renders every card and progressively enhances the grid with
a small native browser script. Do not add a client:* directive: links and
content work before JavaScript runs; filtering activates once the module loads.
Internal absolute paths (starting with /) in href are automatically prefixed
with the site’s base path, matching the behaviour of the Card component.