Skip to main content

Start Developing

Before you begin​

For all new applications you are good to continue with the install guide.

Alert information

For existing applications there are some helpful guides available in order to upgrade to the latest.

Start by configuring your registry​

Before you can install the chroma components locally you will need to configure your .npmrc file.

You can use the Nexus registry or GitHub Packages.

.npmrc​

Nexus

If you are using the Nexus registry then you will need to add the following to your .npmrc file.

registry=https://nexus3.auiag.corp/repos/repository/iag-npm-all/
legacy-peer-deps=true

GitHub Packages

If you are using GitHub Packages then you will need to add the following to your .npmrc file.

Alert warning

When using GitHub Packages, the scope is @iag-ct (not @iag). Keep that in mind when reading our documentation.

You will also need a GitHub token. See How to generate a GitHub token(opens in new window).

@iag-ct:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

.yarnrc.yml (optional)​

If you use yarn then you may need the following in your .yarnrc.yml

npmRegistryServer: "https://registry.npmjs.org/"

npmScopes:
  iag:
    npmRegistryServer: "https://nexus3.auiag.corp/repos/repository/iag-npm-all/"
  iag-ct:
    npmAlwaysAuth: true
    npmAuthToken: ${GITHUB_TOKEN}
    npmRegistryServer: "https://npm.pkg.github.com/"

Install the Package​

Alert information

We recommend using the bundled package

Bundled Package​

The bundled package includes all chroma components within a single packaged version.

Alert warning

When using GitHub Packages, the scope is @iag-ct (not @iag)

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

Individual Packages (optional)​

If you have a smaller application and only require a few components you can install them individually, however we recommend using the bundled package for larger applications.

yarn add @iag/chroma-react-ui-utils.brand-provider
yarn add @iag/chroma-react-ui.alert
yarn add @iag/chroma-react-ui.button
etc....

Using the components in your app​

Using the Chroma component package is the same as any other NPM package.

Import the brand provider and alert components​

import { BrandProvider, Alert } from "@iag/chroma-react-ui.components";
Alert information

Make sure to set a brand for the brand provider to work correctly. More info can be found in the brand provider component page.

import { BrandProvider, Alert } from "@iag/chroma-react-ui.components";
import "./styles.css";
function App() {
  const brand = "chroma";
  return (
    <div className="App">
      <BrandProvider brand={brand}>
        <h1 className="text-primary">Heading</h1>
        <Alert variant="information" className="mb-3">
          <h3>Information Alert</h3>
          <p>Information alert content</p>
        </Alert>
      </BrandProvider>
    </div>
  );
}
export default App;

At this step you should be able to see an alert component styled within your application.

Add Tailwind CSS to generate the utility styling​

Alert information

Chroma uses Tailwind CSS(opens in new window) to generate all the utility classes for styling.

Tailwind CSS also integrates seamlessly with our brand tokens, and best of all it's easy to setup and use within your application.

Install Tailwind CSS​

Start by installing the tailwind package.

npm install -D tailwindcss postcss autoprefixer

Initiate the tailwind config​

Running this command will generate a tailwind.config.js file within your workspace.

This file is needed for Tailwind to generate all the utility classes.

npx tailwindcss init -p

Default tailwind.config.js​

Your config file should look similar to this example below.

Also you may need to change the src/ folder to match your setup locally. (Optional)

module.exports = {
  content: ["./src/**/*.{html,js}"], // change location if needed
  theme: {
    extend: {},
  },
  plugins: [],
};

Adding the brand config from Chroma​

Chroma has a Tailwind config available as a package which you can easily add to your local tailwind config to generate all the required classes.

Alert information

See the chroma tailwind package installation guide for more information.

module.exports = {
  presets: [
    require("@iag/chroma-react-ui-utils.tailwind-config/tailwind-config"), // add this package
  ],
  content: ["./src/**/*.{jsx,ts,tsx,mdx,js}"], // update/extend file extensions if needed
  theme: {
    extend: {},
  },
  plugins: [],
};

Adding Tailwind CSS to your local styles​

Next step is to add the Tailwind css to your local styles so that the classes will get generated correctly.

src/styles.css

@tailwind base;
@tailwind components;
@tailwind utilities;

Validate Tailwind is compiling​

You can check if everything is setup correctly by running the Tailwind CLI build.

You should see some tailwind classes getting generated within this file now.

npx tailwindcss -i ./src/styles.css -o ./dist/output.css --watch

Using Tailwind classes​

Assuming the local styles src/styles.css are already being imported wihtin your application and run via your build. Let's now add the new css getting generated from your tailwind config.

Lets add a bottom margin mb-3 to the <Alert /> and also a heading with a text colour class text-primary.

<BrandProvider brand="chroma">
  <h1 className="text-primary">Heading</h1>
  <div className="bg-primary p-3">
    <p className="text-white">Some text</p>
  </div>
  <Alert variant="information" className="mb-3">
    <h3>Information Alert</h3>
    <p>Information alert content</p>
  </Alert>
</BrandProvider>
Alert information

You can view all the brand specific generated classes within the Brand Colours and System Colours documentation.

Completed setup​

So at this point you have now:

  • Configured your registry
  • Installed the chroma components
  • Added the brand provider and alert components to your page
  • Installed and added Tailwind CSS to your local styles
  • Installed the chroma config for all your brand specific classes
  • Added some tailwind styling to your components

You are now setup and ready to continue building out your application.

.npmrc​

registry=https://nexus3.auiag.corp/repos/repository/iag-npm-all/
legacy-peer-deps=true

tailwind.config.js​

module.exports = {
  presets: [
    require("@iag/chroma-react-ui-utils.tailwind-config/tailwind-config"),
  ],
  content: ["./src/**/*.{jsx,ts,tsx,mdx,js}"],
  theme: {
    extend: {},
  },
  plugins: [],
};

styles.css​

@tailwind base;
@tailwind components;
@tailwind utilities;

App.js​

import { BrandProvider, Alert } from "@iag/chroma-react-ui.components";
import "./styles.css";
function App() {
  const brand = "chroma";
  return (
    <div className="App">
      <BrandProvider brand={brand}>
        <h1 className="text-primary">Heading</h1>
        <Alert variant="information" className="mb-3">
          <h3>Information Alert</h3>
          <p>Information alert content</p>
        </Alert>
      </BrandProvider>
    </div>
  );
}
export default App;