---
title: River
description: Use the river component to introduce a feature using a type and media pairing.
keywords: ['feature', 'showcase', 'highlight', 'story']
ready: true
figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=418%3A8416
source: https://github.com/primer/brand/blob/main/packages/react/src/river/River/River.tsx
storybook: '/brand/storybook/?path=/story/components-river--default'
---

```js
import {River, RiverBreakout} from '@primer/react-brand'
```

## Examples

### Default

```jsx
<Stack style={{width: '100%'}}>
  <River>
    <River.Visual>
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>Heading</Heading>
      <Text>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
        felis nam pulvinar risus elementum.
      </Text>
      <Link href="#">Call to action</Link>
    </River.Content>
  </River>
  <River align="end">
    <River.Visual>
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>Heading</Heading>
      <Text>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
        felis nam pulvinar risus elementum.
      </Text>
      <Link href="#">Call to action</Link>
    </River.Content>
  </River>
  <River align="center">
    <River.Visual>
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Label>Label</Label>
      <Heading>Heading</Heading>
      <Text>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
        felis nam pulvinar risus elementum.
      </Text>
      <Link href="#">Call to action</Link>
    </River.Content>
  </River>
</Stack>
```

### GridLine variant

The `gridline` variant adds lateral padding to the River component, making it suitable for use within bordered grid layouts.

```jsx
<Stack style={{width: '100%'}}>
  <River variant="gridline">
    <River.Visual>
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>GridLine variant</Heading>
      <Text>Use the gridline variant when the River needs lateral spacing to align with bordered grid layouts.</Text>
      <Link href="#">Call to action</Link>
    </River.Content>
  </River>
  <River variant="gridline" align="end">
    <River.Visual>
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>GridLine variant</Heading>
      <Text>The variant works with all alignment options.</Text>
      <Link href="#">Call to action</Link>
    </River.Content>
  </River>
</Stack>
```

### Visual with background

Use the `imageBackgroundColor` prop on `River.Visual` to create a full-bleed container with a background color and the image/video centered inside with padding. This is intended for use with the `gridline` variant.

```jsx
<Stack style={{width: '100%'}}>
  <River variant="gridline">
    <River.Visual imageBackgroundColor="subtle">
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>Visual with background</Heading>
      <Text>
        The imageBackgroundColor prop creates a full-bleed container with a subtle background, centering the media with
        padding around it.
      </Text>
      <Link href="#">Call to action</Link>
    </River.Content>
  </River>
  <River variant="gridline" align="end">
    <River.Visual imageBackgroundColor="subtle">
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>Visual with background (end)</Heading>
      <Text>The imageBackgroundColor prop works with all alignment options.</Text>
      <Link href="#">Call to action</Link>
    </River.Content>
  </River>
</Stack>
```

### Image to text ratio

```jsx
<Stack style={{width: '100%'}}>
  {/* 50/50 (default) example */}
  <River>
    <River.Visual>
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>50/50</Heading>
      <Text>
        <strong>By default</strong>, River applies a 50/50 image to text split.
      </Text>
    </River.Content>
  </River>
  {/* 60/40 example */}
  <River imageTextRatio="60:40">
    <River.Visual>
      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
    </River.Visual>
    <River.Content>
      <Heading>60/40</Heading>
      <Text>This example applies an optional 60/40 image to text split.</Text>
    </River.Content>
  </River>
</Stack>
```

### Video

```jsx
<River style={{width: '100%'}} imageTextRatio="60:40">
  <River.Visual hasShadow={false}>
    <video
      loop
      playsInline
      autoPlay
      muted
      poster="https://github.githubassets.com/images/modules/site/issues/issue-tasks-progress-placeholder.png"
    >
      <source
        type="video/mp4; codecs=hevc,mp4a.40.2"
        src="https://github.githubassets.com/images/modules/site/issues/issue-tasks-progress.hevc.mp4"
      />
      <source
        type="video/mp4; codecs=avc1.4D401E,mp4a.40.2"
        src="https://github.githubassets.com/images/modules/site/issues/issue-tasks-progress.h264.mp4"
      />
    </video>
  </River.Visual>
  <River.Content>
    <Heading>Break issues into actionable tasks</Heading>
    <Text>
      Tackle complex issues with task lists and track their status with new progress indicators. Convert tasks into
      their own issues and navigate your work hierarchy.
    </Text>
  </River.Content>
</River>
```

### Alternative heading levels

```jsx
<River style={{width: '100%'}} imageTextRatio="60:40">
  <River.Visual>
    <img src="/images/placeholder.png" alt="placeholder with a gray background color" />
  </River.Visual>
  <River.Content>
    <Heading as="h1">Alternative heading levels</Heading>
    <Text>Use the 'as' prop to specify alternative heading levels. The default is 'h3'.</Text>
  </River.Content>
</River>
```

### Duotone

```jsx
<River style={{width: '100%'}}>
  <River.Visual>
    <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
  </River.Visual>
  <River.Content>
    <Text size="300">
      <b>This first sentence is highlighted</b> and here is where the body copy starts. Remember to keep this nice and
      succinct.
    </Text>
    <Link href="#">Call to action</Link>
  </River.Content>
</River>
```

### River breakout

```jsx
<RiverBreakout style={{width: '100%'}}>
  <RiverBreakout.A11yHeading>Accelerate workflows</RiverBreakout.A11yHeading>
  <RiverBreakout.Visual>
    <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
  </RiverBreakout.Visual>
  <RiverBreakout.Content
    trailingComponent={() => (
      <Timeline>
        <Timeline.Item>
          <b>GitHub Codespaces</b> offers a complete dev environment in seconds.
        </Timeline.Item>
        <Timeline.Item>
          <b>GitHub Copilot</b> is your AI pair programmer that empowers you to complete tasks.
        </Timeline.Item>
      </Timeline>
    )}
  >
    <Text>
      <b>This first sentence is a river breakout headline.</b> And this is where the body copy starts. Remember to keep
      these nice and succinct.
    </Text>
    <Link href="#">Call to action</Link>
  </RiverBreakout.Content>
</RiverBreakout>
```

## Component props

### River `Required`

| Name             | Type                           | Default | Description                                                                                                 |
| :--------------- | :----------------------------- | :-----: | :---------------------------------------------------------------------------------------------------------- |
| `align`          | `'start'`, `'end'`, `'center'` |         | Alignment of text content relative to the Visual position                                                   |
| `imageTextRatio` | `'50:50'`, `'60:40'`           |         | The aspect ratio applied to the image in relation to the adjacent text. Affects overall layout proportions. |
| `variant`        | `'default'`, `'gridline'`      |         | Visual variant. Use `gridline` to add lateral padding for bordered grid layouts.                            |
| `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                                                                    |

### River.Visual and RiverBreakout.Visual `Required`

| Name                   | Type                    | Default | Description                                                                                                                                                                               |
| :--------------------- | :---------------------- | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fillMedia`            | `boolean`               |   true  | Automatically styles images and video to fill and fit the width of the parent. Disable this setting if you have bespoke styling requirements.                                             |
| `children`             | `ReactElement`          |         | Bring your own component (BYOC) `img` or `ReactElement` (E.g. Next.js `Image` component)                                                                                                  |
| `imageBackgroundColor` | `'default'`, `'subtle'` |         | Applies a background color with padding around the media. Use `'subtle'` to create a full-bleed container with the image/video centered inside. Intended for use with `gridline` variant. |
| `hasShadow`            | `boolean`               | `false` | Shadow applied to the `children`. Set be `false` when the child node has a transparent background.                                                                                        |
| `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                                                                                                                                                  |
| `rounded`              | `boolean`               |  `true` | Toggle visually rounded corners. Enabled by default.                                                                                                                                      |

### River.Content and RiverBreakout.Content `Required`

[`Label`](../Label/index.md), [`Text`](../../typography/Text/index.md),[`Heading`](../../typography/Heading/index.md), `Link` are the only `children` accepted. They can be composed in any order, but their rendered output will always be in a predetermined order.

| Name        | Type                                                                                            | Default | Description                                      |
| :---------- | :---------------------------------------------------------------------------------------------- | :-----: | :----------------------------------------------- |
| `children`  | [`Text`](../../typography/Text/index.md),[`Heading`](../../typography/Heading/index.md), `Link` |         | Content that corresponds to the adjacent visual. |
| `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         |

### RiverBreakout

| 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 |

### RiverBreakout.A11yHeading `Required`

| Name       | Type        | Default | Description                                                                         |
| :--------- | :---------- | :-----: | :---------------------------------------------------------------------------------- |
| `children` | `ReactNode` |         | The heading text that will be read aloud to screen readers, but is visually hidden. |