@primer/react-brand/docs/components/BreakoutBanner/react.md

Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.

---
title: Breakout banner
description: Use a breakout banner to break up content on longer pages and highlight important information.
keywords: ['banner', 'promo', 'callout', 'attention', 'highlight']
source: https://github.com/primer/brand/blob/main/packages/react/src/BreakoutBanner/BreakoutBanner.tsx
storybook: '/brand/storybook/?path=/story/components-breakoutbanner--playground'
ready: true
---

```js
import {BreakoutBanner} from '@primer/react-brand'
```

## Examples

### Default

```jsx
<BreakoutBanner>
  <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
  <BreakoutBanner.LinkGroup>
    <Link href="#">Primary action</Link>
  </BreakoutBanner.LinkGroup>
</BreakoutBanner>
```

### Optional description

```jsx
<BreakoutBanner>
  <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
  <BreakoutBanner.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
    felis nam pulvinar risus elementum.
  </BreakoutBanner.Description>
  <BreakoutBanner.LinkGroup>
    <Link href="#">Primary action</Link>
  </BreakoutBanner.LinkGroup>
</BreakoutBanner>
```

### Additional action

```jsx
<BreakoutBanner>
  <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
  <BreakoutBanner.LinkGroup>
    <Link href="#">Primary action</Link>
    <Link href="#">Secondary action</Link>
  </BreakoutBanner.LinkGroup>
</BreakoutBanner>
```

### Vertically stacked actions

```jsx
<BreakoutBanner>
  <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
  <BreakoutBanner.LinkGroup direction="vertical">
    <Link href="#">Primary action</Link>
    <Link href="#">Secondary action</Link>
  </BreakoutBanner.LinkGroup>
</BreakoutBanner>
```

### Alignment

The content alignment can be changed using the `align` prop on the root `BreakoutBanner`. This can be configured to either `start` or `center`.

```jsx
<BreakoutBanner align="center">
  <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
  <BreakoutBanner.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
    felis nam pulvinar risus elementum.
  </BreakoutBanner.Description>
  <BreakoutBanner.LinkGroup>
    <Link href="#">Primary action</Link>
    <Link href="#">Secondary action</Link>
  </BreakoutBanner.LinkGroup>
</BreakoutBanner>
```

### Leading visual

> An accessible label should always be provided for the leading visual.

```jsx
<BreakoutBanner leadingVisual={<LogoGithubIcon size="medium" aria-label="GitHub logo" />}>
  <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
  <BreakoutBanner.LinkGroup>
    <Link href="#">Primary action</Link>
  </BreakoutBanner.LinkGroup>
</BreakoutBanner>
```

### Optional background image

```jsx
<ThemeProvider colorMode="dark">
  <BreakoutBanner
    backgroundImageSrc={{
      narrow: 'https://github.com/user-attachments/assets/a28110fd-d019-41a4-8f80-b49ae8895708',
      regular: 'https://github.com/user-attachments/assets/a28110fd-d019-41a4-8f80-b49ae8895708',
      wide: 'https://github.com/user-attachments/assets/a28110fd-d019-41a4-8f80-b49ae8895708',
    }}
  >
    <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
    <BreakoutBanner.LinkGroup>
      <Link href="#">Primary action</Link>
    </BreakoutBanner.LinkGroup>
  </BreakoutBanner>
</ThemeProvider>
```

### Optional background color

```jsx
<BreakoutBanner backgroundColor="var(--base-color-scale-blue-0)">
  <BreakoutBanner.Heading>Where the most ambitious teams build great things</BreakoutBanner.Heading>
  <BreakoutBanner.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
    felis nam pulvinar risus elementum.
  </BreakoutBanner.Description>
  <BreakoutBanner.LinkGroup>
    <Link href="#">Primary action</Link>
    <Link href="#">Secondary action</Link>
  </BreakoutBanner.LinkGroup>
</BreakoutBanner>
```

## Component props

### BreakoutBanner `Required`

| name                      | type                                                   | default     | required | description                                                      |
| ------------------------- | ------------------------------------------------------ | ----------- | -------- | ---------------------------------------------------------------- |
| `children`                | `ReactNode`, `ReactNode[]`                             | `undefined` | `true`   | Content to include within the banner component                   |
| `align`                   | `'start' \| 'center'`                                  | `'start'`   | `true`   | The horizontal positioning of content wihin the banner component |
| `backgroundColor`         | `'default' \| 'subtle' \| 'string' \| 'ResponsiveMap'` | `'subtle'`  | `false`  | Optional, custom background color                                |
| `backgroundImageSrc`      | `'string' \| 'ResponsiveMap'`                          | `undefined` | `false`  | Optional, custom background image                                |
| `backgroundImagePosition` | `'string' \| 'ResponsiveMap'`                          | `'center'`  | `false`  | Optional, custom background position                             |
| `backgroundImageSize`     | `'string' \| 'ResponsiveMap'`                          | `'cover'`   | `false`  | Optional, custom background position size                        |
| `leadingVisual`           | `ReactElement`, `Icon`                                 | `undefined` | `false`  | An optional leading visual that appears before the heading       |

### BreakoutBanner.Heading `Required`

| name       | type                                           | default     | required | description                                                           |
| ---------- | ---------------------------------------------- | ----------- | -------- | --------------------------------------------------------------------- |
| `children` | `ReactNode`, `ReactNode[]`                     | `undefined` | `true`   | Content to be displayed inside the `BreakoutBanner.Heading` component |
| `as`       | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h3'`      | `false`  | Heading level                                                         |
| `size`     | `'1' \| '2' \| '3' \| '4' \| '5' \| '6'`       | `'4'`       | `false`  | Visual heading size, irrespective of level                            |

### BreakoutBanner.Description

Optional child that can be used to provide additional information.

| name       | type                       | default     | required | description                                         |
| ---------- | -------------------------- | ----------- | -------- | --------------------------------------------------- |
| `children` | `ReactNode`, `ReactNode[]` | `undefined` | `true`   | Content to be displayed inside the banner component |

### BreakoutBanner.LinkGroup

| name        | type                                            | default        | required | description                                  |
| ----------- | ----------------------------------------------- | -------------- | -------- | -------------------------------------------- |
| `children`  | `Link`                                          | `undefined`    | `true`   | The links to be displayed within the group   |
| `direction` | `'horizontal' \| 'vertical' \| 'ResponsiveMap'` | `'horizontal'` | `false`  | Positioning of the links across x and y axis |

All components forward `id`, `className` and `ref` by default

## Related components

- [CTABanner](../CTABanner/index.md): For highlighting important information and actions towards the end of a page
- [Bento](../Bento/index.md): For more complex layout needs when presenting multiple content blocks