# Cards

Link cards, child-page grids, and prev/next page navigation.

> For the index of this section of the site, see [llms.txt](https://better-static-sites.github.io/llms.txt)

# Cards

Components for navigational content:

*   `Card`: a standalone link card
*   `CardGrid`: a responsive grid wrapper for arbitrary `Card` children
*   `ChildCards`: a grid of cards auto-generated from child pages
*   `PageNav`: previous/next page navigation for sequential docs

Current version: **1.0.1** --[npm](https://www.npmjs.com/package/astro-better-cards)

## Installation

```shell-session
$ npm install astro-better-cards
```

## Card

A single link card with optional icon, image, title, description, label, version, and badges.

```jsx
import Card from 'astro-better-cards/Card.astro';

<Card
  href="/"
  title="Getting Started"
  description="Set up your first project in five minutes."
/>
```

### Live example

[Getting Started Install your first astro-better-\ package and have something on the page in five minutes.](https://better-static-sites.github.io/)

### Card props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | (required) | Destination URL |
| `title` | `string` | — | Card heading (HTML allowed) |
| `description` | `string` | — | Card body text |
| `icon` | `string` | — | Icon image URL (light mode) |
| `darkIcon` | `string` | — | Icon image URL (dark mode) |
| `cardImage` | `string` | — | Full-width image at the top of the card |
| `label` | `string` | — | Small badge label |
| `labelFirst` | `boolean` | `false` | Render label before the title |
| `version` | `string` | — | Version string displayed below the title |
| `badges` | `string[]` | — | Badge labels rendered as `<span class="badge badge-{name}">` — requires `.badge` CSS in your project |
| `variant` | `'full' | 'compact' | 'quickstart'` | `'full'` | Card layout variant |
| `comingSoon` | `boolean` | `false` | Grays out the card and disables the link |

## CardGrid

A responsive grid wrapper for manually-specified `Card` children. Use this when your cards have arbitrary hrefs not tied to the content collection (e.g a curated list of links on a landing page).

```jsx
import Card from 'astro-better-cards/Card.astro';
import CardGrid from 'astro-better-cards/CardGrid.astro';

<CardGrid>
  <Card variant="quickstart" href="/docs/quickstarts/react" icon="/img/react.svg" title="React" />
  <Card variant="quickstart" href="/docs/quickstarts/python" icon="/img/python.svg" title="Python" />
</CardGrid>

<!-- three columns -->
<CardGrid columns={3}>
  <Card href="/a" title="Alpha" />
  <Card href="/b" title="Beta" />
  <Card href="/c" title="Gamma" />
</CardGrid>
```

### Live example

[Getting Started Install your first astro-better-\ package.](https://better-static-sites.github.io/)

[Components Browse the full component library.](https://better-static-sites.github.io/)

### CardGrid props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `1 | 2 | 3 | 4` | `2` | Max columns in the grid. Always 1 column on small screens; scales up to N on large screens. |

## ChildCards

Generates a card grid from the child pages of the current folder. Most useful on section index pages. Use `folder` to target a different path, or `depth` to include deeper levels.

```jsx
import ChildCards from 'astro-better-cards/ChildCards.astro';

<!-- children of the current folder (use on a section index page) -->
<ChildCards />

<!-- grandchildren grouped by subfolder, with h2 section headers -->
<ChildCards depth={2} />

<!-- up to 4 levels deep with nested headers (h2, h3, h4) -->
<ChildCards depth={4} />

<!-- explicit folder, 3 columns, compact cards -->
<ChildCards folder="get-started/quickstarts" columns={3} variant="compact" />

<!-- different collection -->
<ChildCards collection="articles" />
```

Pages with `excludeFromNav: true` or `route: false` in their frontmatter do not appear in the grid (if you add `excludeFromNav` to your content schema).

### Live example

[Linked Steps v0.1.0—component Numbered step sequences with CSS counters and a connecting vertical line.](https://better-static-sites.github.io/docs/content/steps.md)

[Tabs v1.0.0—component Zero-JavaScript tabbed content panels with CSS custom property theming.](https://better-static-sites.github.io/docs/content/tabs.md)

[Cards v1.0.1—component Link cards, child-page grids, and prev/next page navigation.](https://better-static-sites.github.io/docs/content/cards.md)

[Tables v0.1.1—component RST-style list-table and grid-table components for structured data.](https://better-static-sites.github.io/docs/content/tables.md)

[Admonitions v0.1.1—component Extensible callout boxes and inline badges for Astro MDX.](https://better-static-sites.github.io/docs/content/admonitions.md)

[Collapsible Content v0.1.0—component Native details/summary disclosure panels with animated chevron and CSS custom property theming.](https://better-static-sites.github.io/docs/content/details.md)

[Declarative Screenshots v0.4.1—componenttool Declarative, Docker-backed screenshots for Astro docs. Define screenshots in MDX; generate PNGs on demand and commit them.](https://better-static-sites.github.io/docs/content/declarative-screenshots.md)

### ChildCards props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collection` | `string` | `'docs'` | Astro content collection name |
| `folder` | `string` | current page URL | Collection-relative (`get-started/foo`), URL-absolute (`/docs/get-started/foo`), or relative (`./sub`, `../other`) path |
| `depth` | `1 | 2 | 3 | 4` | `1` | How many directory levels to descend. Levels past 1 render grouped section headers (`h2` at depth 2, `h2`/`h3` at depth 3, `h2`/`h3`/`h4` at depth 4). |
| `columns` | `1 | 2 | 3 | 4` | `2` | Max columns in the grid. Always 1 column on small screens; scales up to N on large screens. |
| `variant` | `'full' | 'compact' | 'quickstart'` | `'full'` | Card display variant passed to every card in the grid |

## PageNav

Previous/next navigation rendered at the bottom of a page.

Precedence:

1.  prop value
2.  frontmatter `prev`/`next`
3.  automatic detection by sibling `order`

On most pages you can drop `<PageNav />` with no configuration and it will figure out the neighbors on its own.

To force a specific order or override auto-detection, add `prev` and `next` to frontmatter:

```yaml
prev: "step-1"
next: "step-3"
```

Then use the component with no props:

```jsx
import PageNav from 'astro-better-cards/PageNav.astro';

<PageNav />
```

To override on a specific instance without touching frontmatter:

```jsx
<PageNav prev="other-page" next="another-page" />
```

`prev` and `next` accept the same path formats as `folder` in ChildCards: a bare filename (`step-2`), a collection-relative path, or an absolute URL path starting with `/`.

### Live example

### PageNav props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collection` | `string` | `'docs'` | Astro content collection name |
| `prev` | `string` | frontmatter `prev`, then auto-detected | Path to the previous page (relative to current folder, or absolute) |
| `next` | `string` | frontmatter `next`, then auto-detected | Path to the next page |