Skip to content

Latest commit

 

History

History
2530 lines (2007 loc) · 59.6 KB

API.md

File metadata and controls

2530 lines (2007 loc) · 59.6 KB

BackLink

Import

  import BackLink from '@govuk-react/back-link';

Usage

Simple

<BackLink>Back</BackLink>

With custom click handler

<BackLink onClick={this.myCustomFunction}>Back</BackLink>

With href attribute

<BackLink href='#'>Back</BackLink>

References:

Properties

Prop Required Default Type Description
children 'Back' string Text that will appear in the back link
onClick undefined func Custom function to run when the onClick event is fired

Breadcrumb

Import

  import Breadcrumb from '@govuk-react/breadcrumb';

Usage

This component is DEPRECATED.

Please use the Breadcrumbs component instead.

Properties

Prop Required Default Type Description
children true `````` node Breadcrumb contents

Breadcrumbs

Import

  import Breadcrumbs from '@govuk-react/breadcrumbs';

Usage

Simple

<Breadcrumbs>
  <Breadcrumbs.Link href="/section">Section</Breadcrumbs.Link>
  <Breadcrumbs.Link href="/section/sub-section">Sub-section</Breadcrumbs.Link>
  Current page
</Breadcrumbs>

Providing links with, or without React Router

import { Link } from 'react-router-dom';

<Breadcrumbs>
  <Breadcrumbs.Link as={Link} to="/section">Section</Breadcrumbs.Link>
  <Breadcrumbs.Link href="/section">Sub-section</Breadcrumbs.Link>
</Breadcrumbs>

References:

Properties

Prop Required Default Type Description
children true `````` node Breadcrumbs contents

Button

Import

  import Button from '@govuk-react/button';

Usage

Simple

<Button>My button text</Button>

With Icon

import { ButtonArrow } from '@govuk-react/icons';

<Button icon={<ButtonArrow />}>My button text</Button>

References:

TODO:

  • Remove cascade styling for nested elements, specifically svg
  • Consider ensuring text colour automatically switches between black/white based on WCAG guidance

Properties

Prop Required Default Type Description
buttonColour undefined string Override for default button colour
buttonHoverColour undefined string Override for default button hover colour,
which defaults to buttonColour darkened by 5%
buttonShadowColour undefined string Override for default button shadow colour,
which defaults to buttonColour darkened by 15%
buttonTextColour undefined string Override for default button text colour,
which defaults to govuk white
children true `````` node Button text
disabled false bool Renders a disabled button and removes pointer events if set to true
icon undefined node Button icon
start false bool Renders a large button if set to true

Caption

Import

  import Caption from '@govuk-react/caption';

Usage

Simple

<Caption>Caption heading text</Caption>

With another header

import { H1 } from '@govuk-react/heading';

<Caption size="XL">Supporting header text</Caption>
<H1>Main header text</H1>

References

Properties

Prop Required Default Type Description
children true `````` string Text to be rendered as a caption
size 'XL' enum(...Object.keys(CAPTION_SIZES) | ...Object.keys(TYPOGRAPHY_SCALE)) Visual size level, accepts:
XLARGE, LARGE, MEDIUM, XL, L, M
or a numeric size that fits in the GDS font scale list

Checkbox

Import

  import Checkbox from '@govuk-react/checkbox';

Usage

Simple

<Checkbox>Text displayed next to checkbox</Checkbox>

With disabled state

<Checkbox disabled="disabled">Disabled checkbox option</Checkbox>

Checkbox preselected

<Checkbox defaultChecked>Farm or agricultural waste</Checkbox>

Checkbox preselected & disabled

<Checkbox disabled="disabled" defaultChecked>Farm or agricultural waste</Checkbox>

Checkbox with hint text

<Checkbox hint="including English, Scottish, Welsh and Northern Irish">British</Checkbox>

References:

Properties

Prop Required Default Type Description
children true `````` node Text content for checkbox
className undefined string CSS Classname for outermost container
hint undefined node

DateField

Import

  import DateField from '@govuk-react/date-field';

Usage

Simple

<DateField>What is your date of birth?</DateField>

Date with hint text

<DateField hintText="For example, 31 03 1980">
  What is your date of birth?
</DateField>

Date with hint text & error

<DateField
  hintText="For example, 31 03 1980"
  errorText="Error message goes here"
>
  What is your date of birth?
</DateField>

With custom input name props

<DateField hintText="For example, 31 03 1980"
  inputNames={{
    day: 'dayInputName',
    month: 'monthInputName',
    year: 'yearInputName',
  }}
 >
  What is your date of birth?
</DateField>

References:

Properties

Prop Required Default Type Description
children true `````` node
defaultValues { day: undefined, month: undefined, year: undefined, } custom
errorText undefined string Error text
hintText undefined string Optional hint text
input undefined shape[object Object] Properties that are sent to the input, matching final form and redux form input type
inputNames { day: undefined, month: undefined, year: undefined, } shape[object Object] Input name attributes

Details

Import

  import Details from '@govuk-react/details';

Usage

Simple

<Details summary="Help with nationality">
  I am a paragraph of hidden details, to be revealed when summary is clicked
</Details>

References

Properties

Prop Required Default Type Description
children undefined node The content that will be displayed when details are revealed
open false bool Flag to indicate whether to show component open by default
summary true `````` node Text for the details summary link e.g. Help with nationality

DocumentFooterMetadata

Import

  import DocumentFooterMetadata from '@govuk-react/document-footer-metadata';

Usage

Simple

import { Link } from '@govuk-react/link';

const fromData = [
  <Link href="/government/organisations/ministry-of-defence">
    Ministry of Defence
  </Link>,
];

<DocumentFooterMetadata from={fromData} />

DFM From & part of example

import { Link } from '@govuk-react/link';

const fromData = [
  <Link href="/government/organisations/ministry-of-defence">
    Ministry of Defence
  </Link>,
];
const partOfData = [
  <Link href="/government/topics/energy">Energy</Link>,
  <Link href="/government/topics/environment">Environment</Link>,
];

<DocumentFooterMetadata from={fromData} partOf={partOfData} />

DFM From & other data example

import { Link } from '@govuk-react/link';

const fromData = [
  <Link href="/government/organisations/ministry-of-defence">
    Ministry of Defence
  </Link>,
];
const otherData = [
  {
    id: 0,
    title: 'Consultation type',
    content: <Link href="/government/publications">Open</Link>,
  },
  {
    id: 1,
    title: 'Published',
    content: '20 January 2012',
  },
];

<DocumentFooterMetadata from={fromData} other={otherData} />

References:

Properties

Prop Required Default Type Description
from undefined arrayOf[object Object] Array of JSX nodes to render underneath the from: title
other undefined arrayOf[object Object] Array of Objects for any additional items, each object should contain an id, title and content property
partOf undefined arrayOf[object Object] Array of JSX nodes to render underneath the part of: title

ErrorSummary

Import

  import ErrorSummary from '@govuk-react/error-summary';

Usage

Simple

const heading = 'Message to alert the user to a problem goes here';
const description = 'Optional description of the errors and how to correct them';
const errors = [
  {
    targetName: 'national-insurance-number',
    text: 'National Insurance number error',
  },
  {
    targetName: 'description',
    text: 'Description of what you saw error',
  },
];

const onHandleErrorClick = (targetName) => {
  document.getElementsByName(targetName)[0].scrollIntoView();
};

<div>
  <ErrorSummary
    heading={heading}
    description={description}
    onHandleErrorClick={onHandleErrorClick}
    errors={errors}
  />
  <InputField
    name="national-insurance-number"
    hint="It’s on your National Insurance card, benefit letter, payslip or P60."
  >
    National Insurance number
  </InputField>
  <br />
  <TextArea name="description">Description of what you saw</TextArea>
</div>

References:

TODO:

  • Swap out browser dependancy for context API to help with React Native support

Properties

Prop Required Default Type Description
description `````` string Optional description of the errors
errors `````` arrayOf[object Object] Array of errors with text and target element name to scroll into view when clicked
heading 'There is a problem' string Heading text
onHandleErrorClick `````` func onClick function to scroll the target element into view

ErrorText

Import

  import ErrorText from '@govuk-react/error-text';

Usage

Simple

<ErrorText>Example</ErrorText>

References

Properties

Prop Required Default Type Description
children true `````` string Text to describe the error

Fieldset

Import

  import Fieldset from '@govuk-react/fieldset';

Usage

Use the fieldset component when you need to show a relationship between multiple form inputs. For example, you may need to group a set of text inputs into a single fieldset when asking for an address.

Simple

<Fieldset>
  <Fieldset.Legend>Example</Fieldset.Legend>
</Fieldset>

The Fieldset.Legend sub-component supports a size prop compatible with Heading and a isPageHeading prop for use when you wish your legend to be used as a page heading

Custom legend

<Fieldset>
  <Fieldset.Legend size="XL" isPageHeading>Legend as page heading</Fieldset.Legend>
</Fieldset>

References

Properties

Prop Required Default Type Description
children true `````` node

FileUpload

Import

  import FileUpload from '@govuk-react/file-upload';

Usage

Simple

<FileUpload name="group0">Upload a document</FileUpload>

Input with hint text

<FileUpload
  name="group1"
  acceptedFormats=".jpg, .png"
  hint={['This can be in either JPG or PNG format']}
>
  Upload a photo
</FileUpload>

Input with hint text & error

const meta = {
  touched: true,
  error: 'Example',
};

<FileUpload
  name="group1"
  acceptedFormats=".jpg, .png"
  hint={['This can be in either JPG or PNG format']}
  meta={meta}
>
  Upload a photo
</FileUpload>

References:

Properties

Prop Required Default Type Description
acceptedFormats undefined string
children true `````` node
hint undefined string Optional hint text
meta {} shape[object Object] Final form meta object, pending adjustment/removal

Footer

Import

  import Footer from '@govuk-react/footer';

Usage

Simple

<Footer />

Footer with Copyright information

// Import self hosted copyright image
import crest from './govuk-crest.png';

<Footer
  copyright={{
    text: 'Crown copyright',
    link:
      'https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/',
    image: {
      source: crest,
      height: 102,
      width: 125,
    },
  }}
/>;

Footer with navigation. There is also the option to provide footer links with, or without React/Reach Router.

import { Link } from 'react-router-dom';

<Footer>
  <Footer.Navigation>
    <Footer.NavigationLinks heading="Two column list" listColumns={2}>
      <Footer.Link href="/">Navigation item 1</Footer.Link>
      <Footer.Link to="/footer-nav-item-2" as={Link}>Navigation item 2 (Router Link)</Footer.Link>
      <Footer.Link href="/">Navigation item 3</Footer.Link>
      <Footer.Link href="/">Navigation item 4</Footer.Link>
      <Footer.Link href="/">Navigation item 5</Footer.Link>
      <Footer.Link href="/">Navigation item 6</Footer.Link>
    </Footer.NavigationLinks>
    <Footer.NavigationLinks heading="Single column list">
      <Footer.Link href="/">Navigation item 1</Footer.Link>
      <Footer.Link href="/">Navigation item 2</Footer.Link>
      <Footer.Link href="/">Navigation item 3</Footer.Link>
    </Footer.NavigationLinks>
  </Footer.Navigation>
</Footer>

Footer with links in meta area

<Footer meta={
    <Footer.MetaLinks heading="Support links">
      <Footer.Link href="/">Item 1</Footer.Link>
      <Footer.Link to="/footer-meta-item-2" as={Link}>Item 2 (Router Link)</Footer.Link>
      <Footer.Link href="/">Item 3</Footer.Link>
    </Footer.MetaLinks>
  }
/>

Footer with custom content in meta area

<Footer meta={
    <Footer.MetaCustom>
      Built by the <Footer.Link href="/">Government Digital Service</Footer.Link>
    </Footer.MetaCustom>
  }
/>

NB <Footer.Link /> is styled extention of @govuk-react/link

References:

Properties

Prop Required Default Type Description
children undefined node Footer navigation links
container Footer.WidthContainer func Override the default footer container component.
children, copyright and meta will be placed inside this component.
copyright undefined shape[object Object] Copyright information
meta undefined node Meta text and links

FormGroup

Import

  import FormGroup from '@govuk-react/form-group';

Usage

Simple

import Checkbox from '@govuk-react/checkbox';

<FormGroup>
  <Checkbox name="group-1">Example</Checkbox>
</FormGroup>

References

Properties

Prop Required Default Type Description
children true `````` node
error false bool

GridCol

Import

  import GridCol from '@govuk-react/grid-col';

Should always be wrapped by GridRow. Will always render a column at full width if the browser width is below the TABLET breakpoint.

NB our grid is based on flex-box, which differs from govuk-frontend, which instead uses floats, however it is otherwise similar to use.

Usage

Simple

import GridRow from '@govuk-react/grid-row';
import GridCol from '@govuk-react/grid-col';

<Fragment>
  <GridRow>
    <GridCol>
      ...
    </GridCol>
  </GridRow>
  <GridRow>
    <GridCol setWidth="one-half">
      ...
    </GridCol>
    <GridCol setWidth="one-quarter">
      ...
    </GridCol>
    <GridCol setWidth="one-quarter">
      ...
    </GridCol>
  <GridRow>
    <GridCol setWidth="one-third">
      ...
    </GridCol>
    <GridCol setWidth="two-thirds">
      ...
    </GridCol>
  </GridRow>
  <GridRow>
    <GridCol setWidth="one-third" setDesktopWidth="one-quarter">
      ...
    </GridCol>
    <GridCol setWidth="two-thirds" setDesktopWidth="auto">
      ...
    </GridCol>
  </GridRow>
</Fragment>

References:

Properties

Prop Required Default Type Description
children undefined node GridCol content
columnFull false bool Dimension setting for the column (deprecated)
columnOneHalf false bool Dimension setting for the column (deprecated)
columnOneQuarter false bool Dimension setting for the column (deprecated)
columnOneThird false bool Dimension setting for the column (deprecated)
columnThreeQuarters false bool Dimension setting for the column (deprecated)
columnTwoThirds false bool Dimension setting for the column (deprecated)
setDesktopWidth undefined union(string | number | enum) Explicitly set desktop column to width using value or descriptive string
(one-quarter, one-third, one-half, two-thirds, three-quarters, full)
setWidth undefined union(string | number | enum) Explicitly set column to width using value or descriptive string
(one-quarter, one-third, one-half, two-thirds, three-quarters, full)

GridRow

Import

  import GridRow from '@govuk-react/grid-row';

Usage

Example

Simple

import GridRow from '@govuk-react/grid-row';
import GridCol from '@govuk-react/grid-col';

<Fragment>
  <GridRow>
    <GridCol>
      ...
    </GridCol>
  </GridRow>
</Fragment>

References:

Properties

Prop Required Default Type Description
children true `````` node One or more GridCol nodes

Header

Import

  import Header from '@govuk-react/header';

Usage

This component is DEPRECATED.

Please use the Heading component instead.

Properties

Prop Required Default Type Description
level 1 number Semantic heading level value between 1 and 6
size undefined enum(...Object.keys(HEADING_SIZES) | ...Object.keys(TYPOGRAPHY_SCALE)) Visual size level, accepts:
XLARGE, LARGE, MEDIUM, SMALL, XL, L, M, S
or a numeric size that fits in the GDS font scale list

Heading

Import

  import Heading from '@govuk-react/heading';

Usage

Simple

<Heading>Heading text</Heading>

To pick different heading levels it is recommended to use the shortcut versions as that will pick the appropriate tag as well as set the appropriate corresponding font size.

Using shortcuts

import { H1, H2, H3, H4, H5, H6 } from "@govuk-react/heading";

<H1>h1</H1>
<H2>h2</H2>
<H3>h3</H3>
<H4>h4</H4>
<H5>h5</H5>
<H6>h6</H6>

Differing sizes

<H6 size={80}>
  H6 with font size 80
</H6>
<Heading as="h2" size="SMALL">
  Heading as h2 with SMALL size
</Heading>
<H3 size="LARGE">H3 with LARGE size</H3>

Props pass through

<Heading onClick={() => { console.log('clicked'); }}>Click me</Heading>

References:

Properties

Prop Required Default Type Description
as undefined string Semantic heading tag to use (e.g. 'h3')
By default element used will be an 'h1'
level undefined number Semantic heading level value between 1 and 6 (deprecated)
size 'XLARGE' enum(...Object.keys(HEADING_SIZES) | ...Object.keys(TYPOGRAPHY_SCALE)) Visual size level, accepts:
XLARGE, LARGE, MEDIUM, SMALL, XL, L, M, S
or a numeric size that fits in the GDS font scale list

HintText

Import

  import HintText from '@govuk-react/hint-text';

Usage

Simple

<HintText>Example</HintText>

References

Properties

Prop Required Default Type Description
children true `````` node Text for the hint

InputField

Import

  import InputField from '@govuk-react/input-field';

Usage

Simple

<InputField name="group0">National Insurance number</InputField>

Input with hint text

<InputField
   name="group1"
   hint={[
     'It’s on your National Insurance card, benefit letter, payslip or P60.',
     <br />,
     'For example, ‘QQ 12 34 56 C’.',
   ]}
 >
   National Insurance number
 </InputField>

Input with hint text & error

 const meta = {
   touched: true,
   error: 'Example',
 };

 <InputField
   name="group1"
   hint={[
     'It’s on your National Insurance card, benefit letter, payslip or P60.',
     <br />,
     'For example, ‘QQ 12 34 56 C’.',
   ]}
   meta={meta}
 >
   National Insurance number
 </InputField>

References:

Properties

Prop Required Default Type Description
children true `````` node
hint undefined node
input {} shape[object Object]
meta {} shape[object Object]

Input

Import

  import Input from '@govuk-react/input';

Usage

Simple

<Input />

References:

TODO:

  • Remove errorColor and provide examples on how to extend the component

Properties

Prop Required Default Type Description
type 'text' string HTML <Input /> type

InsetText

Import

  import InsetText from '@govuk-react/inset-text';

Usage

<InsetText>
 Hello
</InsetText>

References

Properties

Prop Required Default Type Description
children true `````` node

LabelText

Import

  import LabelText from '@govuk-react/label-text';

Usage

Simple

<LabelText>Example</LabelText>

References:

Properties

Prop Required Default Type Description
children true `````` node Text for the label

Label

Import

  import Label from '@govuk-react/label';

Usage

Simple

<Label>Example</Label>

References:

Properties

Prop Required Default Type Description
children true `````` node Text for the label
error false bool Apply error state styling to the component

Layout

Import

  import Layout from '@govuk-react/layout';

THIS COMPONENT IS NO LONGER REQUIRED TO ACHIEVE LAYOUT;

  1. GridCol contains the required gutters, we do not need to provide additional gutter to build an accurate grid layout.

  2. GridRow contains the required display: flex; and associated properties for GridCol.

  3. Main contains the required properties to center a container that matches up with TopNav and house the remaining body of content for the page.

If you feel you may still need a Layout component, please do raise a ticket on Github

Usage

This component provides default padding. You can use this component to wrap Grid components however it is not required.

Simple usage

import GridRow from '@govuk-react/grid-row';
import GridCol from '@govuk-react/grid-col';

<Layout>
  <GridRow>
    <GridCol>
      ...
    </GridCol>
  </GridRow>
</Layout>

References:

Properties

Prop Required Default Type Description
children true `````` node GridRow and GridCol children nodes

LeadParagraph

Import

  import LeadParagraph from '@govuk-react/lead-paragraph';

Usage

Simple

<LeadParagraph>LeadParagraph example</LeadParagraph>

References

Properties

Prop Required Default Type Description
children true `````` node Text in the Lead paragraph

Link

Import

  import Link from '@govuk-react/link';

Usage

Simple

<Link href="/some/page">Example</Link>

It is possible to use this component to style a link from react-router, or reach-router as follows:

import { Link as RouterLink } from 'react-router-dom';

<Link as={RouterLink} to="destination">Router example</Link>

NB if no link destination is set then the link styling will not be applied

References

Properties

Prop Required Default Type Description
children true `````` node link contents
muted false bool show link in a "muted" (grey) style
noVisitedState false bool ensure there is no "visited" style
textColour false bool ensure link is shown in plain text colour

ListItem

Import

  import ListItem from '@govuk-react/list-item';

Usage

Simple

<ListItem>List item example</ListItem>

With a link

import { Link } from '@govuk-react/link';

<ListItem>
  <Link href="https://www.google.com/">List item example</Link>
</ListItem>

References

Properties

Prop Required Default Type Description
children true `````` node List item content

ListNavigation

Import

  import ListNavigation from '@govuk-react/list-navigation';

Usage

Simple

import Link from '@govuk-react/link';

<ListNavigation>
  <Link href="/section-a">Section A</Link>
  <Link href="/section-b">Section B</Link>
</ListNavigation>

Using React Router with Link component for GDS styled links

import { Link as RouterLink } from 'react-router-dom';
import { Link } from '@govuk-react/link';

<ListNavigation listStyleType="circle">
  <Link as={RouterLink} to="/link-a">Link A</Link>
  <Link as={RouterLink} to="/link-b">Link B</Link>
</ListNavigation>

References:

TODO:

Properties

Prop Required Default Type Description
children true `````` node List navigation content
listStyleType undefined string CSS value for list-style-type

LoadingBox

Import

  import LoadingBox from '@govuk-react/loading-box';

Usage

Simple

<LoadingBox loading>
  Lorem ipsum dolor sit amet
</LoadingBox>

Loading box complex

<LoadingBox
   loading={false}
   backgroundColor={'#fff'}
   timeIn={800}
   timeOut={200}
   backgroundColorOpacity={0.85}
   spinnerColor={'#000'}
>
  Lorem ipsum dolor sit amet
</LoadingBox>

References:

Properties

Prop Required Default Type Description
backgroundColor WHITE string Background color (3 or 6 Hex char) of loading spinner overlay when loading is true.
backgroundColorOpacity 0.85 number Opacity of loading spinner backgroud colour when loading is true
children true `````` node One or more children nodes that loading box will overlay
loading false bool Whether loading is currently set to true or false
spinnerColor BLACK string Color (3 or 6 Hex char) of loading spinner
timeIn 800 number Length of fade-in animation in milliseconds
timeOut 200 number Length of fade-out animation in milliseconds
title undefined string Loading spinner title text

Main

Import

  import Main from '@govuk-react/main';

Provides a container which aligns to the topNav component, is centered, and provides top padding.

Usage

Example

Simple

import GridRow from '@govuk-react/grid-row';
import GridCol from '@govuk-react/grid-col';

<Main>
  <GridRow>
    <GridCol>
      ...
    </GridCol>
  </GridRow>
</Main>

TODO

  • Implement the 1020px min-width MQ to constants

Properties

Prop Required Default Type Description
children undefined node Child nodes for the page being built

MultiChoice

Import

  import MultiChoice from '@govuk-react/multi-choice';

Usage

Simple

import Radio from '@govuk-react/radio';

<MultiChoice label="example">
   <Radio name="group1" inline>
     Yes
   </Radio>
   <Radio name="group1" inline>
     No
   </Radio>
</MultiChoice>

References:

Properties

Prop Required Default Type Description
children true `````` node
hint undefined string
label true `````` node
meta {} shape[object Object]

OrderedList

Import

  import OrderedList from '@govuk-react/ordered-list';

Usage

Simple

import OrderedList from '@govuk-react/ordered-list';
import ListItem from '@govuk-react/list-item';

<OrderedList>
  <ListItem>Lorem ipsum dolor sit.</ListItem>
  <ListItem>Consectetur adipiscing elit.</ListItem>
  <ListItem>Curabitur et libero nec.</ListItem>
</OrderedList>

with Roman

import OrderedList from '@govuk-react/ordered-list';
import ListItem from '@govuk-react/list-item';

<OrderedList listStyleType="lower-roman">
  <ListItem>Lorem ipsum dolor sit.</ListItem>
  <ListItem>Consectetur adipiscing elit.</ListItem>
  <ListItem>Curabitur et libero nec.</ListItem>
</OrderedList>

References

TODO

Properties

Prop Required Default Type Description
children true `````` node One or more ListItem components
listStyleType undefined string CSS value for list-style-type, or bullet or number to match govuk-frontend

Page

Import

  import Page from '@govuk-react/page';

Usage

Simple

import BackLink from '@govuk-react/back-link';
import { H1 } from '@govuk-react/heading';

<Page beforeChildren={<BackLink href="#" />}>
  <H1>Page title</H1>
</Page>

References

Properties

Prop Required Default Type Description
beforeChildren undefined node Content that needs to appear outside the main page wrapper (see main).
For example: A back link component, breadcrumbs, phase banner component
children undefined node Page contents
container Page.WidthContainer func Override the default page container component.
beforeChildren and children (wrapped in main) will be placed inside this component.
footer undefined node Override the default page footer component.
header <TopNav /> node Override the default page header component.
id 'content' string ID for page content
main Page.Main func Override the default wrapper component for main page content

Pagination

Import

  import Pagination from '@govuk-react/pagination';

Usage

Simple usage with asPaginationItem HOC

import { asPaginationItem } from '@govuk-react/hoc';

const PaginationAnchor = asPaginationItem('a');

<Pagination>
  <PaginationAnchor href="#prev" previousPage>
    Previous page
  </PaginationAnchor>
  <PaginationAnchor href="#next" nextPage>
    Next page
  </PaginationAnchor>
</Pagination>

References:

Properties

Prop Required Default Type Description
children true `````` node asPaginationItem nodes

Panel

Import

  import Panel from '@govuk-react/panel';

Usage

Simple

<Panel title="Application complete" />

Panel with header and HTML body

<Panel title="Application complete">
  Your reference number<br />
  <strong>HDJ2123F</strong>
</Panel>

References:

Properties

Prop Required Default Type Description
children undefined node Panel body text
title true `````` string Panel title text

Paragraph

Import

  import Paragraph from '@govuk-react/paragraph';

Supports bold, italic, links, inline code and block code in Markdown ONLY. This is to ensure we follow GDS as closely as possible. It is worth noting that GDS recommends avoiding bold and italics.

Bold should be avoided in general as not only can it dilute the message, it will also cause Screenreaders to increase the volume of any bold text to reflect the increase in font-weight.

Usage

Simple

<Paragraph>Lorem `ipsum` **dolor** sit *amet* with [some link](https://google.com)</Paragraph>

As supporting text

<Paragraph supportingText>Lorem `ipsum` **dolor** sit *amet* with [some link](https://google.com)</Paragraph>

With a block of code

<Paragraph>
  Some other text...
  ```
  Some Code Block
  ```
  Some more text.
</Paragraph>

With React router

const ReactRouterLinkRenderer = ({ href, children }) => (
  href.match(/^\//)
    ? <Link to={href}>{children}</Link>
    : <a href={href}>{children}</a>
);

<Paragraph linkRenderer={ReactRouterLinkRenderer}>
  ...
</Paragraph>

References

TODO

  • Add test for supporting text
  • Review code snippet styling
  • Remove magic numbers from inline code styling blocks

Properties

Prop Required Default Type Description
children '' node Text content supporting markdown
linkRenderer props => <Link {...props} /> func
supportingText false bool Is this paragraph supporting text for another element?

PhaseBanner

Import

  import PhaseBanner from '@govuk-react/phase-banner';

Usage

Alpha

<PhaseBanner level="alpha">
   This part of GOV.UK is being rebuilt &#8211;{' '}
   <AnchorLink href="https://example.com">find out what that means</AnchorLink>
 </PhaseBanner>

Beta

<PhaseBanner level="beta">
   This part of GOV.UK is being rebuilt &#8211;{' '}
   <AnchorLink href="https://example.com">find out what that means</AnchorLink>
 </PhaseBanner>

References:

Properties

Prop Required Default Type Description
children true `````` node Children text and links
level true `````` string Alpha or beta banner

Radio

Import

  import Radio from '@govuk-react/radio';

Usage

Simple

<Radio name="group1">Radio button text example</Radio>

Radio stacked

 <div>
   <Radio name="group1">Waste from animal carcasses</Radio>
   <Radio name="group1">Waste from mines or quarries</Radio>
   <Radio name="group1">Farm or agricultural waste</Radio>
 </div>

Radio inline

 <div>
   <Radio name="group1" inline>
     Yes
   </Radio>
   <Radio name="group1" inline>
     No
   </Radio>
 </div>

Radio disabled

 <div>
   <Radio name="group1" disabled="disabled">
     Disabled checkbox option
   </Radio>
 </div>

Radio preselected

 <div>
   <Radio name="group1" checked>
     Farm or agricultural waste
   </Radio>
 </div>

Radio preselected & disabled

 <div>
   <Radio name="group1" disabled="disabled" checked>
     Farm or agricultural waste
   </Radio>
 </div>

Radio with hint text

<div>
  <Radio
   name="group1"
   hint="You'll have a user ID if you've registered for Self Assessment or filed a tax return
         online before."
  >
    Sign in with Government Gateway
  </Radio>
</div>

References:

Properties

Prop Required Default Type Description
children true `````` node
className undefined string
hint undefined node
inline false bool

RelatedItems

Import

  import RelatedItems from '@govuk-react/related-items';

Usage

Simple

import { H3 } from '@govuk-react/heading';
import UnorderedList from '@govuk-react/unordered-list';
import Link from '@govuk-react/link';
import ListItem from '@govuk-react/list-item';

<RelatedItems>
  <H3>Example heading</H3>
  <UnorderedList listStyleType="none">
    <ListItem>
      <Link href="https://example.com">Link A</Link>
    </ListItem>
  </UnorderedList>
</RelatedItems>

References:

TODO:

  • Replace CSS selectors with imported components

Properties

Prop Required Default Type Description
children true `````` node Related items content

SearchBox

Import

  import SearchBox from '@govuk-react/search-box';

Usage

Simple

import Layout from '@govuk-react/layout';
import GridRow from '@govuk-react/grid-row';
import GridCol from '@govuk-react/grid-col';

<Layout>
   <GridRow>
     <GridCol>
       <SearchBox placeholder="Search GOV.UK">SearchBox example</SearchBox>
     </GridCol>
   </GridRow>
 </Layout>

References:

Properties

Prop Required Default Type Description
placeholder undefined string

SectionBreak

Import

  import SectionBreak from '@govuk-react/section-break';

Usage

Simple

<SectionBreak>Example</SectionBreak>

References

Properties

Prop Required Default Type Description
level `````` enum('XL' | 'XLARGE' | 'L' | 'LARGE' | 'M' | 'MEDIUM')
visible undefined bool

Select

Import

  import Select from '@govuk-react/select';

Usage

Simple

 <Select name="group1" label="This is a label">
    <option value="0">GOV.UK elements option 1</option>
    <option value="1">GOV.UK elements option 2</option>
    <option value="2">GOV.UK elements option 3</option>
  </Select>

Select with hint text

<Select
   name="group1"
   label="This is a label"
   hint={[
     'This is and example of hintText/description of what we need from you.',
   ]}
 >
   <option value="0">GOV.UK elements option 1</option>
   <option value="1">GOV.UK elements option 2</option>
   <option value="2">GOV.UK elements option 3</option>
 </Select>

Select with hint text & error

const meta = {
  touched: true,
  error: 'Example',
};

<Select
   name="group1"
   label="This is a label"
   hint={[
     'This is and example of hintText/description of what we need from you.',
   ]}
   meta={meta}
 >
   <option value="0">GOV.UK elements option 1</option>
   <option value="1">GOV.UK elements option 2</option>
   <option value="2">GOV.UK elements option 3</option>
 </Select>

Standalone input with inline label

import LabelText from '@govuk-react/label-text';
import { SelectInput } '@govuk-react/select';

<label>
   <LabelText>Sort by:&nbsp;
     <SelectInput>
       <option value="0">People</option>
       <option value="1">Animals</option>
       <option value="2">Vegetables</option>
     </SelectInput>
   </LabelText>
 </label>

References:

Properties

Prop Required Default Type Description
children true `````` node
errorText undefined string
hint undefined string
input {} shape[object Object]
label true `````` string
meta {} shape[object Object]

SkipLink

Import

  import SkipLink from '@govuk-react/skip-link';

Usage

Use the skip link component to help keyboard-only users skip to the main content on a page.

Simple

<SkipLink href="#main-content">Skip to main content</SkipLink>

References

Properties

Prop Required Default Type Description
children 'Skip to main content' node
href '#content' string

SupportingHeader

Import

  import SupportingHeader from '@govuk-react/supporting-header';

Usage

This component is DEPRECATED.

Please use the Caption component instead.

Properties

Prop Required Default Type Description
children true `````` string Text to be rendered as a supporting header

Table

Import

  import Table from '@govuk-react/table';

Usage

The Table component provides a construction kit of elements to create a table

Component default

<Table caption="Dates and amounts">
 <Table.Row>
   <Table.CellHeader>First 6 weeks</Table.CellHeader>
   <Table.Cell>£109.80 per week</Table.Cell>
 </Table.Row>
 <Table.Row>
   <Table.CellHeader>Next 33 weeks</Table.CellHeader>
   <Table.Cell>£109.80 per week</Table.Cell>
 </Table.Row>
 <Table.Row>
   <Table.CellHeader>Total estimated pay</Table.CellHeader>
   <Table.Cell>£4,282.20</Table.Cell>
 </Table.Row>
 <Table.Row>
   <Table.CellHeader>Tell the mother&rsquo;s employer</Table.CellHeader>
   <Table.Cell>28 days before they want to start maternity pay</Table.Cell>
 </Table.Row>
</Table>

Numeric tabular data

const example2Head = (
  <Table.Row>
    <Table.CellHeader>Month you apply</Table.CellHeader>
    <Table.CellHeader numeric>Rate for vehicles</Table.CellHeader>
    <Table.CellHeader numeric>Rate for bicycles</Table.CellHeader>
  </Table.Row>
);

<Table
 caption="Attention, I am the caption of this ship!"
 head={example2Head}
>
  <Table.Row>
    <Table.CellHeader>January</Table.CellHeader>
    <Table.Cell numeric>£165.00</Table.Cell>
    <Table.Cell numeric>£85.00</Table.Cell>
  </Table.Row>
  <Table.Row>
    <Table.CellHeader>February</Table.CellHeader>
    <Table.Cell numeric>£165.00</Table.Cell>
    <Table.Cell numeric>£85.00</Table.Cell>
  </Table.Row>
  <Table.Row>
    <Table.CellHeader>March</Table.CellHeader>
    <Table.Cell numeric>£151.00</Table.Cell>
    <Table.Cell numeric>£77.00</Table.Cell>
  </Table.Row>
  <Table.Row>
    <Table.CellHeader>April</Table.CellHeader>
    <Table.Cell numeric>£136.00</Table.Cell>
    <Table.Cell numeric>£70.00</Table.Cell>
  </Table.Row>
</Table>

Setting custom column widths

<Table
  caption="Custom header"
  head={
    <Table.Row>
      <Table.CellHeader setWidth="one-half>Wide header</Table.CellHeader>
      <Table.CellHeader setWidth="30%">Regular</Table.CellHeader>
      <Table.CellHeader>Normal</Table.CellHeader>
    </Table.Row>
  }
>
  <Table.Row>
    <Table.Cell>Header makes this column one-half wide</Table.Cell>
    <Table.Cell>And this one 30%</Table.Cell>
    <Table.Cell>Another</Table.Cell>
  </Table.Row>
</Table>

References:

Properties

Prop Required Default Type Description
body undefined node Table body rows and cells (for backward compatibility)
caption undefined string Table caption title
children undefined node Table body rows and cells (recommended way)
head undefined node Table header rows and cells

Tabs

Import

  import Tabs from '@govuk-react/tabs';

Import

import Tabs from '@govuk-react/tabs';
Simple Example
class App extends Component {
  constructor() {
    super();
    this.state = { tabIndex: 0 };
    this.setTabIndex = this.setTabIndex.bind(this);
    this.handleClick = this.handleClick.bind(this);
  }

  setTabIndex(newTabIndex) {
    this.setState({
      tabIndex: newTabIndex,
    }));
  }

  handleClick(e, index) {
    const mql = window.matchMedia(`(min-width: ${BREAKPOINTS.TABLET})`);
    if (mql.matches) {
      e.preventDefault();
    }
    return this.setTabIndex(index);
  }

  render() {
    const { tabIndex } = this.state;
    return (
      <Tabs>
        <Tabs.Title>Content</Tabs.Title>
        <Tabs.List>
          <Tabs.Tab
            onClick={(event) => this.handleClick(event, 0)}
            selected={tabIndex === 0}
            href="#first-panel"
          >
            Title 1
          </Tabs.Tab>
          <Tabs.Tab
            onClick={(event) => this.handleClick(event, 1)}
            selected={tabIndex === 1}
            href="#second-panel"
          >
            Title 2
          </Tabs.Tab>
        </Tabs.List>
        <Tabs.Panel selected={tabIndex === 0} id="first-panel">Panel content 1</Panel>
        <Tabs.Panel selected={tabIndex === 1} id="second-panel" >Panel content 2</Panel>
      </Tabs>
    );
  }
}
Hooks Example
const App = ({ defaultIndex }) => {
  const [tabIndex, setTabIndex] = React.useState(defaultIndex);

  const handleTabChange = newTabIndex => setTabIndex(newTabIndex);

  function handleClick({ event: e, index }) {
    const mql = window.matchMedia(`(min-width: ${BREAKPOINTS.TABLET})`);
    if (mql.matches) {
      e.preventDefault();
    }
    return handleTabChange(index);
  }

  return (
    <Tabs>
      <Tabs.Title>Content</Tabs.Title>
      <Tabs.List>
       {[
          {
            content: 'Title 1',
            href: '#first-panel',
          },
          {
            content: 'Title 2',
            href: '#second-panel',
          },
        ].map(({ content, href }, index) => (
          <Tabs.Tab
            onClick={(event) => handleClick({ event, index })}
            selected={tabIndex === index}
            href={href}
          >
           {content}
          </Tabs.Tab>
        ))}
      </Tabs.List>
      {[
        {
          content: 'Panel content 1',
          id: 'first-panel',
        },
        {
          content: 'Panel content 2',
          id: 'second-panel',
        },
      ].map(({ content, id }, index) => (
        <Tabs.Panel
          selected={tabIndex === index}
          id={id}
        >
         {content}
        </Tabs.Panel>
      ))}
    </Tabs>
  );
}

References:

Properties

Prop Required Default Type Description
children true `````` node child components that will appear in the Tabs section

Tag

Import

  import Tag from '@govuk-react/tag';

Usage

Simple

<Tag>beta</Tag>

References:

Properties

Prop Required Default Type Description
inactive false bool

TextArea

Import

  import TextArea from '@govuk-react/text-area';

Usage

Simple

<TextArea name="group1">Description of what you saw</TextArea>

TextArea with hint text

<TextArea name="group1" hint={['Enter as many words as you like']}>
  Description of what you saw
</TextArea>

TextArea with hint text & error

const meta = {
  touched: true,
  error: 'Example',
};

<TextArea
   name="group1"
   hint={['Enter as many words as you like']}
   meta={meta}
 >
   Description of what you saw
 </TextArea>

References:

Properties

Prop Required Default Type Description
children true `````` node
hint undefined string
input {} shape[object Object]
meta {} shape[object Object]

TopNav

Import

  import TopNav from '@govuk-react/top-nav';

Usage

TopNav with logo, service title and navigation items

import CrownIcon from '@govuk-react/icon-crown';
import SearchBox from '@govuk-react/search-box';
import TopNav, { asNavLinkAnchor, asTopNavAnchor } from '@govuk-react/top-nav';

const LogoAnchor = asTopNavAnchor('a');
const NavAnchor = asNavLinkAnchor('a');

const link = 'https://example.com?=1';

const Company = (
  <LogoAnchor href={link} target="new">
    <TopNav.IconTitle icon={<CrownIcon width="36" height="32" />}>GOV.UK</TopNav.IconTitle>
  </LogoAnchor>
);

const ServiceTitle = (
  <NavAnchor href={link} target="new">
    Service Title
  </NavAnchor>
);

const Search = (
  <SearchBox placeholder="Search">hi</SearchBox>
);

<TopNav company={Company} serviceTitle={ServiceTitle} search={Search} active={0}>
  <NavAnchor href="https://example.com?q=catdog" target="new">Navigation item #1</NavAnchor>
  <NavAnchor href="https://example.com?q=dogcat" target="new">Navigation item #2</NavAnchor>
</TopNav>
import { BrowserRouter, Link } from 'react-router-dom';
import CrownIcon from '@govuk-react/icon-crown';
import TopNav, { asLogoAnchor, asNavLinkAnchor } from '@govuk-react/top-nav';

const LogoLink = asTopNavAnchor(Link);
const NavLink= asNavLinkAnchor(Link);

const reactRouterLink = '/section';
const CompanyLink = (
  <LogoLink to={reactRouterLink}>
    <TopNav.IconTitle icon={<CrownIcon width="36" height="32" />}>GOV.UK</TopNav.IconTitle>
  </LogoLink>
);

const ServiceTitleLink = (
  <NavLink to={reactRouterLink}>
    Service Title
  </NavLink>
);

<BrowserRouter>
  <TopNav company={CompanyLink} serviceTitle={ServiceTitleLink} />
</BrowserRouter>

References:

TODO:

  • TODO: this component is a work in progress and needs to more closely match existing examples
  • TODO: is TopNav the right name? What's it called in other GDS styles/patterns?
  • TODO: (The name Header is ambiguous)
  • TODO: #205 Use context api and/or render props for active navigation items
  • TODO: Vertical alignment here needs some work, perhaps should be its own component
  • TODO: Icon should be lined up with font baseline, e.g. vertical-align: baseline

Properties

Prop Required Default Type Description
bgColor BLACK string Top nav background color
children undefined node List Navigation items with anchor tags e.g. NavAnchor components
color WHITE string Top nav text color
company <IconTitle icon={<CrownIcon width="36" height="32" />}>GOV.UK</IconTitle> node Company component e.g. GOV UK
defaultOpen false bool Is the mobile navigation open by default?
search false node Search component
serviceTitle undefined node Service title component e.g. Food Standards Authority

UnorderedList

Import

  import UnorderedList from '@govuk-react/unordered-list';

Usage

Simple

import UnorderedList from '@govuk-react/unordered-list';
import ListItem from '@govuk-react/list-item';

<UnorderedList>
  <ListItem>Lorem ipsum dolor sit.</ListItem>
  <ListItem>Consectetur adipiscing elit.</ListItem>
  <ListItem>Curabitur et libero nec.</ListItem>
</UnorderedList>

with Roman

import UnorderedList from '@govuk-react/unordered-list';
import ListItem from '@govuk-react/list-item';

<UnorderedList listStyleType="lower-roman">
  <ListItem>Lorem ipsum dolor sit.</ListItem>
  <ListItem>Consectetur adipiscing elit.</ListItem>
  <ListItem>Curabitur et libero nec.</ListItem>
</UnorderedList>

References

Properties

Prop Required Default Type Description
children true `````` node One or more ListItem components
listStyleType undefined string CSS value for list-style-type, or bullet or number to match govuk-frontend

VisuallyHidden

Import

  import VisuallyHidden from '@govuk-react/visually-hidden';

Usage

This component is primarily intended to be used for material that will be visually hidden but visible to screen-reader devices.

Simple

<VisuallyHidden>Example</VisuallyHidden>

References

Properties

Prop Required Default Type Description
children true `````` node Content to be hidden
focusable false bool Allow component to be focusable, and thus become visible
important true bool Set styles with !important

WarningText

Import

  import WarningText from '@govuk-react/warning-text';

Usage

Simple

<WarningText>Example</WarningText>

References:

Properties

Prop Required Default Type Description
children true `````` node Warning text to be displayed