@primer/react-brand
Version:
Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.
296 lines (263 loc) • 14.2 kB
Markdown
---
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. |