The Carbon Addons ICS project is a set of React UI components, Sass styles, variables and mixins. As you may have guessed from the name, these components are add-ons to the Carbon Design System, but made specifically for people building user interfaces for ICS. These components will help you build great experiences for ICS, without the hassle of writing boilerplate code.

To preview all of the components and styles, visit our Storybook, or if you’re designing your project using Sketch, download our Design Kit.

Today, we’re going to set up an app using Create React App, and use some React components from Carbon Addons ICS

Tools you’ll need

In order to follow this tutorial, you’ll need a package manager like yarn or npm – I’m going to use npm in the instructions below. 

You’ll also notice I’m using npx, a package runner for npm, to start off our project – this requires that you’re using npm 5.2.0 or greater on your machine. To get the latest version of npm on your machine, run:

npm install -g npm@latest

Setting up the project

Once you’re good to go with npm / npx, head to your terminal, navigate to the directory you want to keep this project in, and type:

npx create-react-app@1 my-ics-app

This will install all off the dependencies needed for using create-react-app. Be sure to include the “@1” version here – as this is what we’re basing the instructions on below. After this completes, you should see a success message like this:

Next, we’ll want to navigate to our new directory, “my-ics-app”, and install carbon-addons-ics, as well as node-sass-chokidar and npm-run-all which we’ll be using to process Sass files:

cd my-ics-app
npm install carbon-addons-ics node-sass-chokidar npm-run-all –save

After npm finishes installing dependencies, open the project in your favourite code editor (Im using VS Code, which is free) and head to the package.json file in the root of our project. 

Replace the scripts section in package.json with following lines:

“scripts”: {
    “build-css”: “node-sass-chokidar –include-path ./src –include-path ./node_modules src/ -o src/”,
    “watch-css”: “npm run build-css && node-sass-chokidar –include-path ./src –include-path ./node_modules src/ -o src/ –watch –recursive”,
    “start-js”: “react-scripts start”,
    “start”: “npm-run-all -p watch-css start-js”,
    “build-js”: “react-scripts build”,
    “build”: “npm-run-all build-css build-js”,
    “eject”: “react-scripts eject”
  }

By doing this, we’re allowing Create React App to look in the right places for our Sass partials.  A current requirement of Carbon Addons ICS is to include paths to node_modules in our Node Sass configuration. Updating the above values for scripts will do this for us, without having to eject from Create React App – great!

Next, we’ll want to create a new stylesheet in our project, in the src folder, and call it App.scss. At the top of this file, add the following line:

@import ‘carbon-addons-ics/scss/index-themed.scss’;
 
.App {
  padding: 1rem; // Some padding around the app div to keep things pretty
}

This will add all of the styles from the Carbon Addons ICS project, which suits our needs for the app we’re going to build in this tutorial. For future apps, you may want to only import certain partials to keep your stylesheet as light as possible – check out the contents of carbon-addons-ics/scss/index.scss to get a better idea of which partials are available for you to import in your project.

Head back to your terminal and type in npm start. If all went according to plan, you should be given a new localhost url. When you go to this address in your browser, you should see a screen like this:

Adding components

Now that we have our project set up, let’s start adding some React components! 

Find src/App.js and open it in your code editor. 

First, we want to remove everything between the <div className=”App”></div> tags, to remove the default text and images added by Create React App. 

Once that’s done, we can dive and start adding ICS React components.

The first component I’m going to use for this demo is the Module component, and I’m going to use a fluid module, as I want my page to be responsive. First, I’m going to import the components I need by adding the following line to the top of App.js:

import { Module, ModuleHeader, ModuleBody } from ‘carbon-addons-ics’;

Then, I’m going to add the Module component to the JSX:

import React, { Component } from ‘react’;
import { Module, ModuleHeader, ModuleBody } from ‘carbon-addons-ics’;
import ‘./App.css’;
 
class App extends Component {
  render() {
    return (
      <div className=”App”>
        <Module>
            <ModuleHeader>Welcome to my ICS App</ModuleHeader>
            <ModuleBody>
              <p>Welcome to the registration page. We’d love for you to get involved with our community!</p>
              <p>Simply register and we’ll send out updates for upcoming talks. 👍</p>
            </ModuleBody>
          </Module>
      </div>
    );
  }
}
 
export default App;

Visiting your project in your browser, you should see a screen like this:

Next, let’s nest some other components within our Module component. When our user visits the app, I want to let them press the button, and get a modal registration form. For this, we can use the ModalWrapper component, which encapsulates a modal within a Button component. 

Update the import statement at the top of src/App.js to include the ModalWrapper.

import { Module, ModuleHeader, ModuleBody, ModalWrapper } from carbon-addons-ics;

Once you’ve done that, we can add the ModalWrapper component within the ModuleBody, in our JSX:

          <ModuleBody>
              <p>Welcome to the registration page. We’d love for you to get involved with our community!</p>
              <p>Simply register and we’ll send out updates for upcoming talks. 👍</p>
              <ModalWrapper
                buttonTriggerText=”Register”
                modalHeading=”Please enter your details”
              >
              </ModalWrapper>
          </ModuleBody>

You’ll notice we’ve added some props to the ModalWrapper. These allow us to set both the text on the trigger Button, and the heading of the Modal when it pops up on screen (you can browse through all available props for these components in Storybook, by clicking the “Show Info” button in the component viewer). Once you’ve done this, head back to your project in your browser and try out the modal.

Finally, let’s add a TextArea component within the ModalWrapper to capture our users details. Again, we’ll update the import statement at the top of our src/App.js:

import { Module, ModuleHeader, ModuleBody, ModalWrapper, TextArea } from ‘carbon-addons-ics’;

Then, let’s nest the TextArea component within the ModalWrapper, in our JSX:

         <ModalWrapper
                buttonTriggerText=”Register”
                modalHeading=”Please enter your details”
              >
              <TextArea labelText=”Address” />
        </ModalWrapper>

Head back to your browser, and click on the button that triggers the modal – you should see something like this:

As you can see from building up this project, it’s dead simple to nest components within one another to create complex user interfaces. 

The examples here only scratch the surface of what you can do with Carbon Addons ICS – so be sure to have a look around the Storybook to find out what else you can use. 

Here’s our src/App.js with everything added in:

import React, { Component } from ‘react’;
import { Module, ModuleHeader, ModuleBody, ModalWrapper, TextArea } from ‘carbon-addons-ics’;
import ‘./App.css’;
 
class App extends Component {
  render() {
    return (
      <div className=”App”>
        <Module>
            <ModuleHeader>Welcome to my ICS App</ModuleHeader>
            <ModuleBody>
              <p>Welcome to the registration page. We’d love for you to get involved with our community!</p>
              <p>Simply register and we’ll send out updates for upcoming talks. 👍</p>
              <ModalWrapper
                buttonTriggerText=”Register”
                modalHeading=”Please enter your details”
              >
              <TextArea labelText=”Address” />
              </ModalWrapper>
            </ModuleBody>
          </Module>
      </div>
    );
  }
}
 
export default App;

In my next post, I’ll be walking you through how to add some of the Sass mixins and variables provided with Carbon Addons ICS. These will help you use consistent typography, colours, shadows, and more.

In the meantime, if you’d like to post an issue, or even contribute to Carbon Addons ICS, head on over to our Github repository.

Here’s to your next great ICS React app, happy coding!

Jimmy Loughran
Front End Developer
Avatar

Join The Discussion

Your email address will not be published. Required fields are marked *