ModeProvider

Installation

The ModeProvider is a named export from the @nib-components/theme package.

npm install @nib-components/theme

Usage

import {ModeProvider} from '@nib-components/theme';

const Page = () => <ModeProvider mode="feature">{children}</ModeProvider>;

Interactive demo

// Try changing the mode to 'default' or 'alt'
<ModeProvider mode="feature">
  <Box background="default" color="default" padding={6}>
    <Stack space={4}>
      <Heading size={2}>Hello world</Heading>
      <Copy>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</Copy>
      <PrimaryButton>Primary Button</PrimaryButton>
    </Stack>
  </Box>
</ModeProvider>

The ModeProvider component is used to specify the mode for its children. It will create a styled-components globalStyle for the current mode/brand combination and inject the appropriate CSS Custom Properties, sourced from @nib-group/design-tokens, into the head.

ModeProvider must be wrapped by the Theme to know what the current brand is and the mode prop is required.

ModeProvider components can be nested.

Props

mode

The mode in which to render all children. Required.

mode prop can either be a string to apply universally, or an object with brands as keys.

The possible values vary across brands but there are some that are common to all brands:

• default
• alt
• feature

"nib" also has sage, sunset and warm. When using a mode that is not supported by a brand, it will simply do nothing and look up the tree to the next ModeProvider.

The Theme component has a nested ModeProvider with a mode prop set to "default".

import {ModeProvider} from '@nib-components/theme';

const Page = () => (
  <ModeProvider mode="alt">
    <div>children here</div>
  </ModeProvider>
);

Setting mode by brand

If your application involves multiple brands, you can pass different modes per brand as below:

import {ModeProvider} from '@nib-components/theme';

const Page = () => (
  <ModeProvider mode={{nib: 'sage', gu: 'alt'}}>
    <div>children here</div>
  </ModeProvider>
);

If you have many brands to support, we have a special key of rest which will apply to any brand not set in the dictionary:

import {ModeProvider} from '@nib-components/theme';
/**
 * Example app supporting nib, gu, qantas, ing and tid
 */
const Page = () => (
  <ModeProvider mode={{nib: 'feature', rest: 'alt'}}>
    <div>children here</div>
  </ModeProvider>
);

Alternatively you can always nest ModeProviders:

import {ModeProvider} from '@nib-components/theme';
/**
 * Example app supporting nib, gu, qantas, ing and tid
 */
const Page = () => (
  <ModeProvider mode="alt">
    <ModeProvider mode={{nib: 'feature'}}>
      <div>children here</div>
    </ModeProvider>
  </ModeProvider>
);

A combination of nesting and the rest key should be able to cover most use cases. Please reach out if you need something more.

Wrapping mesh components

Mesh components have been updated to consume tokens and therefore respond to the mode set by the ModeProvider. This means that you can place any mesh component inside a ModeProvider and it will respond to the mode set.

Some components may look better than others in feature mode, and some brands may still require some tweaks to their token values. Please reach out if anything doesn't look right.

Related components

• Theme