> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olonjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hero — full-width landing page header with CTA buttons

> The Hero section displays a large headline, optional image, and up to two CTA buttons. Use it as the primary above-the-fold section on landing pages.

The `hero` section is the primary above-the-fold component for landing pages. It renders a large headline (with an optional highlighted span), a subtitle, and one or two CTA buttons side by side. You can optionally attach an image that renders alongside or behind the copy, depending on your theme.

Use `hero` once per page, as the very first section, when you want maximum visual impact and a clear entry-point action for visitors.

***

## Data fields

<ParamField body="label" type="string">
  A small eyebrow label rendered above the main title — for example `"An OlonJS collections demo"`. Optional. Use it to add context or a campaign tag without changing the headline.
</ParamField>

<ParamField body="title" type="string" required>
  The primary headline. Rendered in the largest type on the page. If you also supply `titleHighlight`, this field holds the first (un-highlighted) part of the headline — for example `"Notes on the"`.
</ParamField>

<ParamField body="titleHighlight" type="string">
  An optional second span of the headline that your theme renders in an accent color or with a decorative treatment — for example `"craft of software"`. OlonJS concatenates `title` and `titleHighlight` visually while keeping them separate fields so the highlight can be styled independently.
</ParamField>

<ParamField body="subtitle" type="string" required>
  A sentence or short paragraph of supporting copy rendered below the headline. Aim for one to three sentences that set expectations and reinforce the primary CTA.
</ParamField>

<ParamField body="primaryCta" type="CtaSchema" required>
  The main call-to-action button. Always rendered. See [CtaSchema fields](#ctaschema-fields) below.
</ParamField>

<ParamField body="secondaryCta" type="CtaSchema">
  An optional second call-to-action rendered beside the primary button. Use it to offer an alternative path — for example a "Browse topics" link alongside a "Read the posts" primary action.
</ParamField>

<ParamField body="image" type="ImageSelectionSchema">
  An optional image rendered in the hero layout. See [ImageSelectionSchema fields](#imageselectionschema-fields) below.
</ParamField>

***

### CtaSchema fields

Each CTA object (both `primaryCta` and `secondaryCta`) uses the following shape:

<ParamField body="id" type="string" required>
  A unique identifier for this CTA button. Used as the React key and for analytics targeting — for example `"home-hero-cta-1"`.
</ParamField>

<ParamField body="label" type="string" required>
  The visible button text — for example `"Read the posts"`.
</ParamField>

<ParamField body="href" type="string" required>
  The URL or path the button links to — for example `"/posts"` or `"https://example.com"`.
</ParamField>

<ParamField body="variant" type="&#x22;primary&#x22; | &#x22;secondary&#x22; | &#x22;ghost&#x22;" required>
  Controls the button's visual style. Use `"primary"` for the most prominent action, `"secondary"` for a supporting action, and `"ghost"` for a low-emphasis link-style button.
</ParamField>

***

### ImageSelectionSchema fields

<ParamField body="url" type="string" required>
  The fully qualified URL of the image — for example an Unsplash URL or a path to a file in your `/public` folder.
</ParamField>

<ParamField body="alt" type="string" required>
  Descriptive alt text for the image, used by screen readers and rendered as the `alt` attribute on the `<img>` element.
</ParamField>

***

## Settings fields

Settings live in the `settings` object alongside `data` in the section JSON.

<ParamField body="paddingTop" type="&#x22;none&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22;">
  Vertical padding applied above the section. Defaults to the theme base when omitted. Use `"xl"` on the first section of a page to clear the navigation bar.
</ParamField>

<ParamField body="paddingBottom" type="&#x22;none&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22;">
  Vertical padding applied below the section. Set to `"none"` when the next section bleeds directly into the hero background.
</ParamField>

***

## JSON example

The following example is taken directly from `home.json`:

```json theme={null}
{
  "id": "home-hero",
  "type": "hero",
  "data": {
    "label": "An OlonJS collections demo",
    "title": "Notes on the",
    "titleHighlight": "craft of software",
    "subtitle": "Essays on design, engineering and process — published as a living demo of cross-collection relations: every post belongs to many tags, and every tag knows its posts without storing them twice.",
    "primaryCta": {
      "id": "home-hero-cta-1",
      "label": "Read the posts",
      "href": "/posts",
      "variant": "primary"
    },
    "secondaryCta": {
      "id": "home-hero-cta-2",
      "label": "Browse topics",
      "href": "/tags",
      "variant": "secondary"
    },
    "image": {
      "url": "https://images.unsplash.com/photo-1456735190827-d1262f71b8a3?w=2000&q=80",
      "alt": "Fountain pen nib in sharp close-up over paper"
    }
  },
  "settings": {
    "paddingTop": "xl",
    "paddingBottom": "none"
  }
}
```

<Tip>
  Setting `paddingBottom` to `"none"` is a common pattern when the next section (such as a `posts-list` or `stats-band`) uses a contrasting background that should appear flush against the hero.
</Tip>

***

## Used on pages

The `hero` section is typically used **once** on the home page (`home.json`) as the first section. Interior pages use [`page-hero`](/reference/sections/page-hero) instead, which renders a more compact banner suited to content pages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.