Skip to content

react.mdx

Latest commit

 

History

History
267 lines (237 loc) · 12.4 KB

react.mdx

File metadata and controls

267 lines (237 loc) · 12.4 KB
Raw
title River
description Use the river component to introduce a feature using a type and media pairing.
keywords
feature
showcase
highlight
story
show-tabs true
tab-label React
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

import {Label} from '@primer/react' import {RiverAlignProp, RiverImageTextRatio, RiverVariantProp} from './react'

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

Examples

Default

<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 and applies a full-bleed visual background by default, making it suitable for use within bordered grid layouts.

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

Image to text ratio

<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

<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

<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

<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

<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)
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, Text,Heading, 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,Heading, 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.