# FilterableCardGrid

> A card grid with a built-in searchbox for live filtering by title, description, tags, or badges.

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.

```astro
---
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

<PropsTable component="components/FilterableCardGrid" />

## Examples

<Example label="With summaries and tags">
  <FilterableCardGrid
    columns={2}
    label="Filter components"
    items={[
      {
        title: "Card",
        href: "/docs/components/card/",
        description: "Linkable container with title, body, and optional image.",
        tags: ["layout"],
      },
      {
        title: "CardGrid",
        href: "/docs/components/card-grid/",
        description: "Responsive grid for arranging cards in 2 or 3 columns.",
        tags: ["layout"],
      },
      {
        title: "Callout",
        href: "/docs/components/callout/",
        description: "Highlighted aside for notes, warnings, and tips.",
        tags: ["content"],
      },
      {
        title: "YouTubeEmbed",
        href: "/docs/components/youtube-embed/",
        description: "A privacy-conscious, click-to-load video embed.",
        tags: ["content", "media"],
        badges: ["Progressive enhancement"],
      },
    ]}
  />
</Example>

## Keyboard shortcuts

- <kbd>/</kbd> --- focus the searchbox from anywhere on the page (ignored when
  typing in another input)
- <kbd>Escape</kbd> --- 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 supplied `label` as its
  `aria-label`.
- A live region announces the current match count whenever the query changes.
- The keyboard hint (`<kbd>/</kbd>`) is marked `aria-hidden`.
- Cards remain regular `<a>` elements --- focus order, hover states, and link
  behaviour match the standard `Card` component.

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