---
title: Hero
description: Use the hero component to render a full-width banner at the top of a page.
keywords: ['heading', 'intro', 'cta', 'banner']
ready: true
figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=431%3A8481
source: https://github.com/primer/brand/blob/main/packages/react/src/Hero/Hero.tsx
storybook: '/brand/storybook/?path=/story/components-hero--default'
---

```js
import {ActionMenu, Button, Hero} from '@primer/react-brand'
```

## Examples

### Default

```jsx
<Hero>
  <Hero.Label>Label</Hero.Label>
  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
  <Hero.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
    felis nam pulvinar risus elementum.
  </Hero.Description>
  <Hero.ButtonGroup>
    <Button as="a" href="#">
      Primary action
    </Button>
    <Button as="a" href="#">
      Secondary action
    </Button>
  </Hero.ButtonGroup>
</Hero>
```

### Action menus

`Hero.ButtonGroup` accepts up to two `Button` or `ActionMenu` children and applies the primary variant to the first item and the secondary variant to the second. Set `variant` on `Button` or `ActionMenu.Button` to override it.

```jsx
<Hero>
  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
  <Hero.ButtonGroup>
    <Button as="a" href="#">
      Primary action
    </Button>
    <ActionMenu>
      <ActionMenu.Button>More actions</ActionMenu.Button>
      <ActionMenu.Overlay aria-label="More actions">
        <ActionMenu.Item value="contact-sales">Contact sales</ActionMenu.Item>
        <ActionMenu.Item value="view-pricing">View pricing</ActionMenu.Item>
      </ActionMenu.Overlay>
    </ActionMenu>
  </Hero.ButtonGroup>
</Hero>
```

### Images

`Hero` can display an optional foreground image. Use `position` to alternate between various layouts.

```jsx
<Stack>
  <Hero>
    <Hero.Label>Actions</Hero.Label>
    <Hero.Heading>Automate your workflow from idea to production</Hero.Heading>
    <Hero.ButtonGroup>
      <Button as="a" href="#">
        Get started with Actions
      </Button>
    </Hero.ButtonGroup>
    <Hero.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
  </Hero>
  <br />
  <Hero align="center">
    <Hero.Label>Actions</Hero.Label>
    <Hero.Heading size="2">Automate your workflow from idea to production</Hero.Heading>
    <Hero.ButtonGroup>
      <Button as="a" href="#">
        Get started with Actions
      </Button>
    </Hero.ButtonGroup>
    <Hero.Image
      position="inline-end"
      src="/images/placeholder.png"
      alt="placeholder, blank area with a gray background color"
      style={{height: '100%'}}
    />
  </Hero>
</Stack>
```

### GridLine variant

Use `variant="gridline"` to display the Hero with a contained image, subtle background color, and borders.

The `GridLine` variants all feature a trailing border by default. Use `Box` if you need to add one to the top also.

```jsx
<Hero variant="gridline" align="center">
  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
  <Hero.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
    felis nam pulvinar risus elementum.
  </Hero.Description>
  <Hero.ButtonGroup>
    <Button as="a" href="#">
      Primary action
    </Button>
  </Hero.ButtonGroup>
  <Hero.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
</Hero>
```

### GridLine "Expressive" variant

Use `variant="gridline-expressive"` for an alternative split-content layout.

The `GridLine` variants all feature a trailing border by default. Use `Box` if you need to add one to the top also.

```jsx
<Hero variant="gridline-expressive">
  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
  <Hero.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
    felis nam pulvinar risus elementum.
  </Hero.Description>
  <Hero.ButtonGroup>
    <Button as="a" href="#">
      Primary action
    </Button>
  </Hero.ButtonGroup>
  <Hero.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
</Hero>
```

### Video

`Hero` includes support for inserting videos.

Use [VideoPlayer](../VideoPlayer/index.md), a native `<video>` element or a YouTube embed as valid `children`. Similarly to `Hero.Image`, use the `position` prop to alternate between various layouts.

```jsx
<Hero>
  <Hero.Label>Label</Hero.Label>
  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
  <Hero.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
    felis nam pulvinar risus elementum.
  </Hero.Description>
  <Hero.ButtonGroup>
    <Button as="a" href="#">
      Primary action
    </Button>
  </Hero.ButtonGroup>
  <Hero.Video>
    <iframe
      src="https://www.youtube.com/embed/fHwtrOcLAnI"
      title="YouTube video player"
      frameBorder="0"
      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
      referrerPolicy="strict-origin-when-cross-origin"
      allowFullScreen
      style={{width: '100%', height: 'auto', aspectRatio: '16/10'}}
    ></iframe>
  </Hero.Video>
</Hero>
```

### Alignment

`Hero` text alignment can be adjusted by changing the `align` prop.

```jsx
<Hero align="center">
  <Hero.Label>Label</Hero.Label>
  <Hero.Heading>
    Blazing fast cloud
    <br />
    developer environments
  </Hero.Heading>
  <Hero.ButtonGroup>
    <Button as="a" href="#">
      Primary action
    </Button>
  </Hero.ButtonGroup>
</Hero>
```

## Component props

### Hero

| Name              | Type                      |   Default   | Description                                                     |
| :---------------- | :------------------------ | :---------: | :-------------------------------------------------------------- |
| `align`           | `'center'`, `'start'`     |  `'start'`  | Optional text alignment                                         |
| `variant`         | `'default' \| 'gridline'` | `'default'` | Visual variants to the Hero.                                    |
| `enableAnimation` | `boolean`                 |   `false`   | Enables animations for variants and children that support them. |
| `className`       | `string`                  |             | Sets a custom class on the root element                         |
| `ref`             | `React.RefObject`         |             | Forward a Ref to the underlying DOM node                        |

### Hero.Label

| name        | type              | default   | description                                  |
| ----------- | ----------------- | --------- | -------------------------------------------- |
| `variant`   | `TextVariants`    | `'muted'` | Specify alternative text appearance          |
| `className` | `string`          |           | Sets a custom class on the root of the label |
| `id`        | `string`          |           | Sets a custom id on the root of the label    |
| `ref`       | `React.RefObject` |           | Forward a Ref to the underlying DOM node     |

### Hero.Heading

| name        | type              | default | description                              |
| ----------- | ----------------- | ------- | ---------------------------------------- |
| `className` | `string`          |         | Sets a custom class on the root element  |
| `id`        | `string`          |         | Sets a custom id                         |
| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node |

Forwards all props from the [Heading component](../../typography/Heading/index.md), including `as`, `size`, and `weight`.

### Hero.Description

| name        | type           | default              | description                         |
| ----------- | -------------- | -------------------- | ----------------------------------- |
| `className` | `string`       |                      | Sets a custom CSS class             |
| `variant`   | `TextVariants` | `defaultTextVariant` | Specify alternative text appearance |

Forwards `size` and `weight` props from the [Text component](../../typography/Text/index.md).

### Hero.ButtonGroup

Groups up to two [Button](../Button/index.md) or [ActionMenu](../ActionMenu/index.md) children. Forwards all props from the [ButtonGroup component](../ButtonGroup/index.md).

### Hero.PrimaryAction

Deprecated. Use `Hero.ButtonGroup` with a `Button` child instead.

| name        | type          | default | description                         |
| ----------- | ------------- | ------- | ----------------------------------- |
| `className` | `string`      |         | Primary link custom class           |
| `href`      | `string`      |         | `href` for primary link             |
| `as`        | `a`, `button` | `a`     | Applies the underlying HTML element |

Forwards all props from the [Button component](../Button/index.md).

### Hero.SecondaryAction

Deprecated. Use `Hero.ButtonGroup` with a `Button` child instead.

| name        | type          | default | description                         |
| ----------- | ------------- | ------- | ----------------------------------- |
| `className` | `string`      |         | Secondary link custom class         |
| `href`      | `string`      |         | `href` for secondary link           |
| `as`        | `a`, `button` | `a`     | Applies the underlying HTML element |

Forwards all props from the [Button component](../Button/index.md).

### Hero.Image

| name       | type                                            | default       | description                                       |
| ---------- | ----------------------------------------------- | ------------- | ------------------------------------------------- |
| `position` | `'block-end' \| 'inline-end' \| 'inline-start'` | `'block-end'` | Controls positioning of the foreground image      |
| `padding`  | `'default'`, `'none'`, `'all'`                  | `'default'`   | Controls padding around media in gridline layouts |

Forwards all props from the [Image component](../Image/index.md), including `src`, `alt`, and `aspectRatio`.

`position` and `padding` props currently only apply to `gridline` variants. The `default` Hero variant ignores non-default media padding and logs a warning during development.

### Hero.Video

| name            | type                                            | default       | description                                                                                                     |
| --------------- | ----------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
| `position`      | `'block-end' \| 'inline-end' \| 'inline-start'` | `'block-end'` | Controls positioning of the child video element                                                                 |
| `padding`       | `'default'`, `'none'`, `'all'`                  | `'default'`   | Controls padding around media in gridline layouts                                                               |
| `poster`        | `string`                                        |               | URL of the poster image to display before video plays. When set, `posterAltText` and `posterTitle` are required |
| `posterAltText` | `string`                                        |               | Alt text for the poster image. Required when `poster` is set                                                    |
| `posterTitle`   | `string`                                        |               | Title text displayed on the poster overlay. Required when `poster` is set                                       |