Astro Integration

Astro components and layouts for building content-focused sites with Vanilla Breeze.

Overview

The Astro integration provides typed components and layouts that follow Vanilla Breeze conventions. All components support Astro's islands architecture and work with content collections.

Location: /integrations/astro/

Installation

Copy the astro/ directory into your Astro project's src/ folder:

 cp -r integrations/astro/* src/

Then import styles in your main CSS or layout:

 --- import '../styles/astro-overrides.css'; ---

Components

BaseHead

Standard <head> setup with meta tags, OG data, and theme initialization.

 --- import BaseHead from './components/BaseHead.astro'; --- <head> <BaseHead title="Page Title" description="Page description" image="/og-image.png" /> </head>

Props:

  • title - Page title (required)
  • description - Meta description (required)
  • image - OG image URL (optional)
  • canonicalURL - Canonical URL (optional)

ThemeToggle

Theme switcher button using the theme-wc web component.

 --- import ThemeToggle from './components/ThemeToggle.astro'; --- <ThemeToggle />

NavTree

Tree navigation from structured data with automatic active state detection.

 --- import NavTree from './components/NavTree.astro'; const nav = [ { label: 'Home', href: '/' }, { label: 'Docs', href: '/docs/', children: [ { label: 'Getting Started', href: '/docs/start/' }, { label: 'Components', href: '/docs/components/' } ] } ]; --- <NavTree items={nav} />

Props:

  • items - Navigation tree array (required)
  • currentPath - Current URL path (optional, auto-detected)
  • density - 'default' | 'compact' (optional)

PageToc

Auto-generated table of contents from page headings.

 --- import PageToc from './components/PageToc.astro'; const { headings } = Astro.props; --- <PageToc headings={headings} />

Props:

  • headings - Array from getHeadings() (required)
  • label - Section label (optional)
  • depth - Max heading depth (optional, default: 3)

Card

Wrapper for the layout-card custom element.

 <Card variant="outlined" interactive href="/item/"> <h3>Card Title</h3> <p>Card content</p> </Card>

Props:

  • variant - 'default' | 'outlined' | 'elevated' (optional)
  • interactive - Makes entire card clickable (optional)
  • href - Link URL when interactive (optional)

FormField

Wrapper for the form-field custom element.

 <FormField label="Email" name="email" type="email" required hint="We'll never share your email." />

Props:

  • label - Field label (required)
  • name - Input name (required)
  • type - Input type (optional, default: 'text')
  • required - Required field (optional)
  • hint - Helper text (optional)
  • error - Error message (optional)

CodeBlock & BrowserWindow

Helper components for demos and documentation.

 <CodeBlock code={codeString} lang="javascript" filename="example.js" /> <BrowserWindow src="/demos/example.html" url="https://example.com" title="Demo" />

Layouts

BaseLayout

Minimal page structure with header and footer.

 --- import BaseLayout from './layouts/BaseLayout.astro'; --- <BaseLayout title="Home" description="Welcome"> <h1>Hello World</h1> </BaseLayout>

DocsLayout

Documentation page with sidebar navigation and table of contents.

 --- import DocsLayout from './layouts/DocsLayout.astro'; --- <DocsLayout title="Getting Started" description="Learn how to use Vanilla Breeze" headings={headings} navigation={nav} > <slot /> </DocsLayout>

BlogLayout

Blog post layout with metadata and author info.

 <BlogLayout title="Post Title" description="Post excerpt" pubDate={new Date('2024-01-15')} author="John Doe" tags={['css', 'web']} > <slot /> </BlogLayout>

LandingLayout

Marketing page with hero support and multi-column footer.

 <LandingLayout title="Product" description="Description"> <section class="hero">...</section> <section class="features">...</section> </LandingLayout>

Styles

Import astro-overrides.css for Astro-specific styles:

  • View transition animations
  • Island loading states
  • Content collection styling
  • Light/dark code block switching

TypeScript Support

The integration includes TypeScript types for all component props. Import from index.ts:

 import type { NavItem, Heading } from './astro'; const nav: NavItem[] = [ { label: 'Home', href: '/' } ];