Using the next theme

We're currently in the process of rolling out a new visual design for our products, driven by the design system. This guide describes how to enable the new visual design in both new and existing projects This guide describes how to enable the new visual design in both new and existing projects.

React

The new visual design is applied entirely via theme context and can be applied either at the BlueprintProvider or with a nested NextProvider.

Global Application

New projects should follow the instructions for getting started, with one small change. When setting up the BlueprintProvider, pass 'all' to the next prop.

This can also be applied to existing projects, ideally controlling the value of next with a feature flag.

Tip
It's also possible to specify a list of features to enable instead of the entire theme, for example: next={['color']}.

App.tsx

import { BlueprintProvider } from '@hover/blueprint';
interface AppProps {
  children: React.ReactNode;
}
const App = ({ children }: AppProps) => (
  <BlueprintProvider next="all">{children}</BlueprintProvider>
);
export { App };

Local Application

The new visual design can also be applied to a single component or subtree by using NextProvider.

Note
These will look the same if you have the /next theme applied globally in the documentation settings.

live

<VStack alignItems="start">
  <HStack>
    <Button>Old Button</Button>
    <Badge colorScheme="warning">Old Badge</Badge>
  </HStack>
  <Divider />
  <NextProvider attach fontsHost="/typography/">
    <HStack>
      <Button>New Button</Button>
      <Badge colorScheme="warning">New Badge</Badge>
    </HStack>
  </NextProvider>
</VStack>

Important
This example has fontsHost set to load the font assets locally in the documentation. Don't set fontsHost unless you're intentionally hosting the fonts locally in your application. By default, the fonts will be loaded from the design system CDN.

Attaching CSS Variables

Because theming is powered by CSS variables, we need to attach the overridden CSS variables to an HTML element. If the immediate child of NextProvider renders and HTML element, you can simply set attach and the provider will set the appropriate id attribute on that element in order for it to recieve the variable definitions.

If you need to attach the variables to an element further down in the tree, you'll need to use the useNextThemeRootClassName hook at set the className attribute.

Router.tsx

import { Route, Switch } from 'react-router';
import { NextProvider, useNextThemeRootClassName } from '@hover/blueprint';
interface NextThemeRootProps {
  children: React.ReactNode;
}
const NextThemeRoot = ({ children }: NextThemeRootProps) => {
  const className = useNextThemeRootClassName();
  <div className={className}>{children}</div>;
};
const Router = () => (
  <Switch>
    <NextProvider>
      <Route path="/new-stuff">
        <NextThemeRoot>{/* some route */}</NextThemeRoot>
      </Route>
      <Route path="/more-new-stuff">
        <NextThemeRoot>{/* some route */}</NextThemeRoot>
      </Route>
    </NextProvider>
    <Route path="/old-stuff">{/* some route */}</Route>
  </Switch>
);