govuk-react
An implementation of the GOV.UK Design System in React using CSSinJS using Object notation (with Emotion).
The following projects (in priority order) are used as a guide for what components to implement and how they should look/behave. Where possible we are using the existing CSS as a guide, but often need to modify to suit custom markup. Also flexbox is preferred over floats.
- GOV.UK Design System (source)
- GOV.UK Design System Backlog (where there are open tickets in the backlog that reference patterns/components in existing govuk sites)
- GOV.UK Frontend
- GOV.UK/elements
- Any other established govuk pattern
Usage
npm install govuk-react emotion react-emotion --saveimport { Button } from 'govuk-react'
const MyComponent = ({title}) => (<div>
<h1>{title}</h1>
<Button />
</div>)See the Storybook for examples of all available components.
Also see the example project for basic usage.
Using anchors/React Router Link
We are using a Higher Order Component (HOC), which takes a component and returns a new component with the original props.
We use the same HOC for an <a href...> as we do for a <Link to...>. For example;
import { BrowserRouter, Link } from 'react-router';
import { asAnchor } from '@govuk-react/hoc';
const MyLink = asAnchor(Link);
const MyComponent = () => (
<nav>
<BrowserRouter>
<MyLink to="https://example.com">example</MyLink>
</BrowserRouter>
</nav>
)Assumptions
Use of these components assumes the following from the peer project:
- Either normalize.css or sanitize.css is used as a CSS reset.
- The GDS Transport font face is included (for gov.uk domains only)
- Other than the reset, no other styles affecting generic elements (without classes, IDs etc) are present in the CSS.
Why Emotion/CSS-in-JS?
See A Unified Styling Language.
We have opted for Emotion over styled-components as we like the support for JS syntax.
We are also expecting to use Interoperable Style Transfer Format (ISTF) once it is finalised and compatible with a CSSinJS library, which would allow us to distribute CSSinJS stylesheets without a runtime.
Why not use GDS styles/classes directly
- We want to be free to write different DOM structure and/or CSS that is more in keeping with a React and bem-ish architecture. (e.g. in React you often don't need to specify IDs for field inputs, and can wrap inputs with labels so that they are automatically associated. We want to leave the decision of whether to use input IDs to the parent project. GDS styles don't wrap inputs with labels and require IDs and for attributes).
- We want a parent project to not have to worry about a specific build system (e.g. for handling
import styles.css, particularly if you want universal support) or including certain CSS files. We want a simplenpm install govuk-reactto be enough to get govuk styled components on to your page, irrespective of your build system.
About the GDS font
Unfortuantely the GDS transport font has a relatively restrictive license described on the gov.uk blog. We are investigating rendering an elegant alternative before falling back to Arial on issue 272.
Related sites and projects
GOV.UK
- govuk-elements (source)
- govuk_frontend_toolkit
- govuk-frontend
- govuk_template (source)
- GOV.UK Design Patterns