Skip to main content

FilterableCardGrid

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

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

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.