# Hero

> The opening section — eyebrow, heading, description, actions and optional media, in three layouts.

URL: https://apogee.avaui.dev/docs/sections/hero
Last updated: 2026-10-15

The opening section — eyebrow, heading, description, actions and optional media, in three layouts.

Last updated October 15, 2026

```astro
<Hero
eyebrow="Design system"
heading="Pages that are fast, accessible and yours"
description="Composable sections built from the same primitives as every component."
primaryAction={{ label: 'Get started', href: '#' }}
secondaryAction={{ label: 'Read the docs', href: '#' }}
/>
```

## Add

```sh
npx @ava-ui/apogee add hero
```

Copies to `sections/Hero/` and pulls in Section, SectionHeader, Button, Grid, Image, utils and the shared section helpers (`sections/_shared/`).

## API

`@composable`. Every section wraps `Section` + `Container`, is a labelled landmark, and reads only tokens.

| Prop | Type | Default | Category | Description |
| --- | --- | --- | --- | --- |
| `eyebrow` | `string` | — | content | Small label above the heading. |
| `heading` | `string` | — | content | Required. |
| `description` | `string` | — | content | Supporting copy. |
| `primaryAction` | `{ label, href }` | — | content | Solid button. |
| `secondaryAction` | `{ label, href }` | — | content | Outline button. |
| `media` | `{ src, alt, width?, height? }` | — | content | Image beside (`split`) or below (`stacked`) the text. Or use the `media` slot. |
| `layout` | `'centered' \| 'split' \| 'stacked'` | `'centered'` | layout | Composition. |
| `align` | `'start' \| 'center'` | by layout | layout | Text alignment; `centered` defaults to `center`. |
| `background` | `'page' \| 'neutral-faded' \| 'primary-faded' \| 'primary' \| 'inverted'` | `'page'` | layout | Surface token. |
| `spacing` | `'small' \| 'medium' \| 'large'` | `'large'` | layout | Vertical rhythm. |
| `headingLevel` | `1 \| 2 \| 3 \| 4` | `1` | layout | Heading element. |
| `id` | `string` | auto | layout | Section id; the heading gets `{id}-heading`. |

## Layouts

```astro
<Hero layout="split" media={{ src, alt }} … />
```

```astro
<Hero layout="stacked" media={{ src, alt }} … />
```

## Backgrounds

```astro
<Hero background="primary" … />
<Hero background="inverted" … />
<Hero background="primary-faded" … />
```

## Accessibility

-   A `section` labelled by its heading; `headingLevel` defaults to `1`, so use one Hero per page or lower the level.
-   Actions are real links styled as buttons; media gets the `alt` you pass.

## Tokens

Reads the Section background tokens and the on-colours; see [SectionHeader](https://apogee.avaui.dev/docs/section-header).

## Content

-   One idea in the heading, one sentence of support, at most two actions.