Getting Started with React

Follow these instructions to use Hover Design System components (📦 @hoverinc/design-system-react-web) in a React application.

Installation

Info
The following instructions assume you are using Yarn 1.x as a package manager

NPM Authentication

All system packages are currently distributed as private packages on npm. Therefore, before we can install @hoverinc/design-system-react-web, we need to configure npm to authenticate to the correct package registries.

Tip
These steps should be copied into your project's readme.md

Create an .npmrc with the following command

npx @hoverinc/configure-npm -s hover
Copy the requested secrets from 1Password as prompted

Install Hover Design System and its dependencies

Verify you have React version 16.8 or greater installed
Install @hoverinc/design-system-react-web and its peerDependencies

yarn add @hoverinc/design-system-react-web @emotion/react@^11 @emotion/styled@^11 framer-motion@^8

Usage

Set up DesignSystemProvider

Any components must be wrapped in a DesignSystemProvider to work correctly. We recommend wrapping your entire application with DesignSystemProvider.

This may differ depending on how your application is set up, but generally it should look like this:

App.tsx

import * as React from 'react';
import { DesignSystemProvider } from '@hoverinc/design-system-react-web';
interface AppProps {
  children: React.ReactNode;
}
const App = ({ children }: AppProps) => (
  <DesignSystemProvider>{children}</DesignSystemProvider>
);
export { App };

Next.js

In a Next.js application, you can use a custom App.

pages/_app.tsx

import { DesignSystemProvider } from '@hoverinc/design-system-react-web';
import { AppProps } from 'next/app';
const App = ({ Component, pageProps }: AppProps) => (
  <DesignSystemProvider>
    <Component {...pageProps} />
  </DesignSystemProvider>
);
export default App;

Customize Theme (optional)

Warning
This should only be necessary for augmenting or adding components that Blueprint does not support. Any necessary customizations should be discussed with the design systems team so we can consider incorporating them upstream in @hoverinc/chakra-theme.

Disclaimer
Modifying the default Blueprint theme can cause unintended side-effects and any modifications may break with new versions of Blueprint. Do so at your own risk!

Create a custom theme file

theme.ts
import { applyThemeOverrides, ThemeOverrides } from '@hoverinc/design-system-react-web'; const themeOverrides: ThemeOverrides = { components: { Breadcrumb: { variants: { brand: { link: { color: 'brandGreen.400', }, }, }, }, }, }; // ⚠️ NOTE: you must export your theme as `theme` for compatibility with Chakra's CLI export const theme = applyThemeOverrides(themeOverrides);
Override built-in theme by passing customTheme to DesignSystemProvider

App.tsx
import * as React from 'react'; import { DesignSystemProvider, ThemeOverrides } from '@hoverinc/design-system-react-web'; import { theme } from './theme'; interface AppProps { children: React.ReactNode; } const App = ({ children }: AppProps) => ( <DesignSystemProvider customTheme={theme}>{children}</DesignSystemProvider> ); export { App };