Skip to main content

Start Developing

Before you begin​

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

info

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

Start by configuring your registry​

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

.npmrc​

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

.yarnrc.yml (optional)​

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

npmRegistryServer: "https://nexus3.auiag.corp/repos/repository/iag-npm-all/"

Install the Package​

info

We recommend using the bundled package

Bundled Package​

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

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

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​

info

Chroma uses Tailwind CSS 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.

info

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>
info

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;