Skip to content
Autumn 2026 Mesh Release and Design Tokens v2 now available! Read the announcement
    DesignDevelopAnalyticsFeedback
    Stable

    ModeProvider

    ModeProvider is a component that allows you to set 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.

    GitHub, opens in a new tab·Storybook, opens in a new tab

    Installation

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

    bash
    npm install @nib-group/mesh-theme

    Usage

    jsx
    import {ModeProvider} from '@nib-group/mesh-theme';
    

    const Page = () => (
      <ModeProvider sentiment="hero" prominence="default" space="relaxed" container="wide">
        {children}
      </ModeProvider>
    );

    Interactive demo

    jsx
    // Try changing the sentiment to 'default' or 'warm' and the prominence to 'gentle' or 'muted'
<ModeProvider sentiment="hero" prominence="default">
  <Box background="default" foreground="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.

    ModeProvider must be used within a Theme to know the current brand. When a sentiment or prominence prop is set, the other is defaulted to default. ModeProvider components can be nested.

    Props

    PropTypeDefaultDescription
    sentimentstring or objectThe sentiment to use. Must be one of the supported sentiments of a brand, or an object with brands as keys and sentiments as values. Different brands support different sentiments.
    prominencestring or objectThe prominence of the sentiment to use. Must be one of [default, gentle, muted, prominent], or an object with brands as keys and modes as values. Not all sentiments support all prominences.
    spacestring or objectThe spacing scale to use. Must be one of [default, compact, condensed, relaxed, spacious], or an object with brands as keys and modes as values.
    containerstring or objectThe container max-width to use. Must be one of [default, narrow, wide], or an object with brands as keys and modes as values.

    sentiment

    The sentiment in which to render all children. Required.

    sentiment 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
    • hero
    • informative
    • cautionary
    • positive
    • negative

    "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.

    Setting modes by brand

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

    jsx
    import {ModeProvider} from '@nib-group/mesh-theme';
    

    const Page = () => (
      <ModeProvider sentiment={{nib: 'sage', gu: 'default'}} prominence="default">
        <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:

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

    Alternatively you can always nest ModeProviders:

    jsx
    import {ModeProvider} from '@nib-group/mesh-theme';
    /**
     * Example app supporting nib, gu, qantas, ing and tid
     */
    const Page = () => (
      <ModeProvider sentiment="default" prominence="gentle">
        <ModeProvider sentiment={{nib: 'hero'}} prominence="default">
          <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 hero mode, and some brands may still require some tweaks to their token values. Please reach out if anything doesn't look right.

    Edit this page