React

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

Installation

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.

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

Create .npmrc

Copy the requested token from 1Password.
Add or update these lines in your .npmrc.
Never commit the token value to source control.

@hoverinc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<YOUR_GITHUB_PACKAGES_TOKEN>

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

Set up DesignSystemProvider

Components must be wrapped in DesignSystemProvider to work correctly—we recommend wrapping your entire application.

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

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

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!

1. Create a custom theme file

Overrides should be defined in 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);

2. Override built-in theme

Import your custom theme overrides and pass to through DesignSystemProvider via customTheme prop. .

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

Bootstrap

React Native