@pangeacyber/react-mui-branding

Motivation

The BrandingThemeProvider can be used wrap your application in a Material-UI ThemeProvider, that has default ThemeOptions built from your fetched Pangea branding configurations.

Getting Started

Install Material-UI library and the BrandingThemeProvider NPM package.

npm

npm install @mui/material @emotion/react @emotion/styled @pangeacyber/react-mui-branding

yarn

yarn add @mui/material @emotion/react @emotion/styled @pangeacyber/react-mui-branding

Peer dependencies

Please note that react and react-dom are peer dependencies too:

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0",
  "react-dom": "^17.0.0 || ^18.0.0"
},

To learn more about Material-UI (MUI) check out their official documentation(https://mui.com/material-ui/getting-started/installation/).

Props

The BrandingThemeProvider component accepts the following props:

• themeOptions (optional): Material UI theme options for the MUI ThemeProvider. If Pangea branding configuration data is fetched, it will merge the build themeOptions with the themeOptions prop.
• children (optional): JSX Element to render as children
• auth (optional): An object representing the authentication configuration. Used to fetch your branding configurations from Pangea
  • clientToken: string;
  • domain: string;
• brandingId (optional): Found in the Project -> Branding page within console is required along with "auth" in order to retrieve Pangea branding configurations.
• ThemeProviderProps (optional): An object container MUI ThemeProvider props overrides
• themeOptions (optional): A partial ThemeOptions object that is merged with the fetched branding configurations ThemeOptions, using lodash/merge. Can override parts of the Pangea branding built MUI ThemeOptions
• overrideThemeOptions (optional): A post hook over the final fetched ThemeOptions before createTheme is called

For a deeper dive into the Prop interface check the source code here

Example

The following is a brief example on how to initialize the AuditLogViewer component.

import React from "react";
import { BrandingThemeProvider } from "@pangeacyber/react-mui-branding";
import {
  Audit,
  AuditLogViewerProps,
  AuditLogViewer,
} from "@pangeacyber/react-mui-audit-log-viewer";

const MyComponent: React.FC = () => {
  return (
    <BrandingThemeProvider
      brandingId={process.env.REACT_APP_BRANDING_ID}
      auth={{
        clientToken: process.env.REACT_APP_CLIENT_TOKEN,
        domain: "aws.us.pangea.cloud",
      }}
    >
      <AuditLogViewer
        initialQuery="message:testing"
        onSearch={handleSearch}
        onPageChange={handlePageChange}
      />
    </BrandingThemeProvider>
  );
};

Customization

The BrandingThemeProvider component is primarily a light wrapper around the Material-UI component library, ThemeProvider component. so styling of the component can be controlled through a MUI Theme. See Theming documentation here

We additionally export utility functions such as fetchBrandingThemeOptions(auth, brandingId, themeOptions = {}, themeOptionsHook = noop) -> Theme, which accepts the same interfaces as the BrandingThemeProvider, to allow you to fetch the Pangea branding MUI Theme outside of react, can be fetched server-side, such that the Theme can be directly passed in ThemeProvider for Material-UI.