---
url: /api/css/hero.md
---
# CSS: hero

`div[class~="instui-hero"]` — Full-width header section with title, subtitle, and optional background image.

✅ Use Hero when:

* You need a prominent page header with visual hierarchy

* The page benefits from a large, eye-catching opening section

* You want to include background imagery or gradient accents
  🚫 Don't use Hero when:

* Building a simple page header — use Page-Layout instead

* The hero competes with critical content — prioritize readability

## Accessibility

* Ensure the title is in an `<h1>` tag for semantic structure
* If using background images, provide sufficient color contrast for text
* Avoid autoplay on video or animation that could distract from content

## Usage

```css
@import "@pantoken/plugin-layouts/layouts.css";
```

## Examples

-automatica11y -nocard

```html
<div class="instui-hero" data-a11y-root>
  <div class="instui-content">
    <h1 class="instui-title">Explore your course</h1>
    <p class="instui-subtitle">Find materials and upcoming work.</p>
    <a class="instui-button" href="#course-content" data-a11y-trigger>View course content</a>
  </div>
</div>
```

## Slots

| Slot | Description |
| --- | --- |
| `subtitle` | Hero subtitle content |
| `title` | Hero title content |

## Parts

| Part | Description |
| --- | --- |
| `.instui-actions` | Optional action buttons or links. |
| `.instui-background` | Optional background layer (image or gradient). |
| `.instui-content` | Container for hero text and actions. |
| `.instui-overlay` | Optional semi-transparent overlay for text contrast. |
| `.instui-subtitle` | Optional supporting text or description. |
| `.instui-title` | Main hero title (typically `<h1>`). |

## Pseudo-elements

| Pseudo-element | Description |
| --- | --- |
| `::before` | — |

## States

| State | Description |
| --- | --- |
| `:optional` | — |

## Tokens consumed

| Token | Type | Value |
| --- | --- | --- |
| `--instui-color-primary-background` | — | — |
| `--instui-font-size-hero` | `<length>` | — |
| `--instui-font-size-large` | `<length>` | — |
| `--instui-font-weight-bold` | — | — |
| `--instui-space-large` | — | — |
| `--instui-space-medium` | — | — |

## Related

* [card](/api/css/card.md)