@royalnavy/react-component-library
v4.23.8
Published
A collection of react components and helpers to assist in building applications for the Royal Navy
Downloads
2,614
Readme
React Component Library
A collection of React components written for Royal Navy web applications.
Installation
The Royal Navy React Component Library is available as an NPM package.
To install it, run the relevant command for your package manager:
// npm
npm install @royalnavy/fonts @royalnavy/react-component-library styled-components
// pnpm
pnpm add @royalnavy/fonts @royalnavy/react-component-library styled-components
Note: styled-components
is a required peer dependency and is installed with the above command.
Usage
import React from 'react'
import ReactDOM from 'react-dom'
import '@royalnavy/fonts'
import { GlobalStyleProvider, Button } from '@royalnavy/react-component-library'
import { lightTheme } from '@royalnavy/design-tokens'
function App() {
return (
<GlobalStyleProvider theme={lightTheme}>
<Button variant="primary">Hello, World!</Button>
</GlobalStyleProvider>
)
}
ReactDOM.render(<App />, document.querySelector('#app'))
<GlobalStyleProvider />
This context provider component applies global Royal Navy Design System styles to your application (resets, normalize and fonts). You should wrap the root of your app in a single instance of this component. (Take care to avoid having multiple instances mounted at once, as this will lead to duplicated global styles.)
Theming
By default the GlobalStyleProvider
will use the lightTheme
exported by the @royalnavy/design-tokens
package. You can create your own themes by injecting your own custom token set via the theme
prop.
We recommend reading the following blog post on styled-theming
. Using this pattern you can selectively theme individual components. Inverting responsibility for the implementation of the theme to the component itself.
When utilising this pattern remember to extend a base token set:
<GlobalStyleProvider theme={{ ...lightTheme, customThemeMode: 'foo' }} />
Hooks
useFloatingElement
This hook aids in the positioning of arbitrary elements relative to a target element. The positioning engine will intelligently position the element based on available screen real-estate.
import { useFloatingElement } from '@royalnavy/react-component-library'
const Example = () => {
const {
targetElementRef,
floatingElementRef,
arrowElementRef,
styles,
attributes,
} = useFloatingElement(placement)
return (
<>
<Target ref={targetElementRef} />
<Float
ref={floatingElementRef}
style={styles.popper}
{...attributes.popper}
>
Hello, World!
</Float>
</>
)
}
The hook wraps a popular underlying positioning engine called Popper.
If you want opinionated styling for your floating element please consider the Popover component.
Questions
The Design System is maintained by a team at the Royal Navy. If you want to know more about the Royal Navy Design System, please email the Design System Team.
Documentation
The documentation website contains all the information you need to build your application using the Royal Navy Design System.
End-to-end tests
End-to-end tests run in both Chrome and Firefox using Playwright. Tests are dependent on the Storybook running with a test configuration:
pnpm run storybook:test
Playwright browsers and dependencies also have to be installed:
pnpm run test:e2e:install
Run all tests
pnpm run test:e2e
Run specific tests
pnpm run test:e2e <regex>
Run all tests with tracing
pnpm run test:e2e:trace
Open the HTML test report
pnpm run test:e2e:show-report
Contributing
The contributing guide resource presents information about our development process.
Changelog
If you have recently updated then read the release notes
Roadmap
The Design System Roadmap Board contains the work that has been prioritised for the next 12 months.