Skip to main content

Brand Provider

The provider sets the brand tokens and base level styling for applications

Installation​

Install

yarn add @iag/chroma-react-ui.components

Import

import { BrandProvider } from '@iag/chroma-react-ui.components';

Set a brand​

The brand prop is used to target the correct brand specific css.

View the list of available brands

<BrandProvider brand="nrma">
  <div>code....</div>
</BrandProvider>

Setting a channel​

Brands can have multiple channels or platforms defined for their brand. A channel can be defined as either web, partner or aem.

Channels allows brands to set and target specific token sets unique to their own channel types. This allows for additional styling not defined within the default branding.

Channel types:

  • web (default) - /css/brands/monochroma/web/base.css.gz
  • partner - /css/brands/monochroma/partner/base.css.gz
  • aem - /css/brands/monochroma/aem/base.css.gz
<BrandProvider brand="nrma" channel="partner">
  <div>code...</div>
</BrandProvider>

Setting a theme​

Brands can potentially have multiple themes. The default will always be the global brand tokens without the need to set this prop.

The following brand(s) have an alternative theme available to use:

  • CGU
    • navy

How to set the theme prop​

<BrandProvider brand="cgu" theme="navy">
  <div>code...</div>
</BrandProvider>

Prevent FOUC issues​

In order to aid with this process we have included onLoaded & onError callback function props to the <BrandProvider /> so that your application can be alerted to the status of the brand tokens css file requested by the browser. We have a <Spinner> component that can be used even without the brand css being loaded, once the BrandProvider has retrieved the tokens this will update to the appropriate brand colour. This could become part of a preloader component in your application for example.

<BrandProvider
  brand="nrma"
  onLoaded={() => console.log("css loaded")}
  onError={() => console.log("css failed to load")}
/>

Using the Brand Provider Context​

You can retreive the brand, channel and version via the useBrandProvider() function as part of the <BrandProvider /> component.

import {
  BrandProvider,
  useBrandProvider,
} from "@iag/chroma-react-ui-utils.brand-provider";
const Component = () => {
  const { brand, channel, version, config } = useBrandProvider();
  return (
    <>
      <p>Brand = {brand}</p>
      <p>Channel = {channel}</p>
      <p>Version = {version}</p>
    </>
  );
};
const App = () => (
  <BrandProvider brand="nrma">
    <Component />
  </BrandProvider>
);

What is the Brand Configuration Object?​

The brand configuration object provides a way for multi-branded applications to manage and control the styling of components for each brand in a simple way.

By targetting the config object values you can define the props of a component without any complex conditional logic within your application.

Using the Brand Configuration​

Each brand has access to the brand configuration layer which provides component specific variant management to control the brand styling. The configuration is provided directly via the <BrandProvider /> component. To use, target the config object via the useBrandProvider() function like the example below.

The config object will retreive the branded object based off the brand passed into the <BrandProvider /> component, in this case it will retrieve the nrma object.

Set a default button variant for the header component​

In this example we are using the config object to manage the <Button /> variant prop. This is useful as some brands may want a different button style to appear when their button is placed in the header. Using this method means we can easily manage that on a brand level.

Extending the Brand Configuration for Specific Brands​

The brand configuration object can be extended for specific brands. In this example we will set a default across all brands to use a primary button variant and a class for the h1 heading. However for nrma we will override the default button variant and h1 classname to use primaryOutline and text-primary instead.

The same can be applied to any other brand within your application in order to control the styling.

import {
  BrandProvider,
  extendBrandConfig,
  useBrandProvider,
} from "@iag/chroma-react-ui-utils.brand-provider";
const updatedConfig = extendBrandConfig({
  default: {
    brand: {
      header: {
        button: {
          variant: "cta1",
        },
      },
    },
  },
});
const Component = () => {
  const { config } = useBrandProvider();
  const cta1 = config?.brand?.header?.button?.cta1?.variant;
  return (
    <>
      <Button variant={cta1}>Button</Button>
    </>
  );
};
const App = () => (
  <BrandProvider brand="nrma" config={updatedConfig}>
    <Component />
  </BrandProvider>
);

Properties​

Name
Description
  • brand
    stringlowercase hyphenated brand name as defined in the brand-tokens repo, eg. nrma, bendigo-bank
  • channel
    stringweb | partner | aem
  • theme
    stringSpecific to CGU branded partner applications
  • className
    string
  • onLoaded
    () => voidcallback function that fires once the tokens css file has finished loading in the browser
  • onError
    () => voidcallback function that fires if the token css file fails to load
  • config
    objectA custom brand configuration object that overrides certain variants for Chroma components per brand
  • localhost
    booleanFor development only - do not use *