Blueprint

GuidesFoundationComponentsReleases
⌘K

Getting Started with React

Follow these instructions to use Blueprint components (📦 @hover/blueprint) 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 @hover/blueprint, we need to configure npm to authenticate to the correct package registries.

Tip

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

  1. Create an .npmrc with the following command


    npx @hover/configure-npm -s hover

  2. Copy the requested secrets from 1Password as prompted

Install Blueprint and its dependencies

  1. Verify you have React version 16.8 or greater installed

  2. Install @hover/blueprint and its peerDependencies


    yarn add @hover/blueprint @emotion/react@^11 @emotion/styled@^11 framer-motion@^8

Usage

Set up BlueprintProvider

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

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 { BlueprintProvider } from '@hover/blueprint';
interface AppProps {
children: React.ReactNode;
}
const App = ({ children }: AppProps) => (
<BlueprintProvider>{children}</BlueprintProvider>
);
export { App };

Next.js

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

pages/_app.tsx

import { BlueprintProvider } from '@hover/blueprint';
import { AppProps } from 'next/app';
const App = ({ Component, pageProps }: AppProps) => (
<BlueprintProvider>
<Component {...pageProps} />
</BlueprintProvider>
);
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 @hover/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

    theme.ts

    import { applyThemeOverrides, ThemeOverrides } from '@hover/blueprint';
    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 by passing customTheme to BlueprintProvider

    App.tsx

    import * as React from 'react';
    import { BlueprintProvider, ThemeOverrides } from '@hover/blueprint';
    import { theme } from './theme';
    interface AppProps {
    children: React.ReactNode;
    }
    const App = ({ children }: AppProps) => (
    <BlueprintProvider customTheme={theme}>{children}</BlueprintProvider>
    );
    export { App };