Skip to main contentCarbon Design System

1. Installing Carbon

Starting with the Carbon Angular, there are two ways to begin working with Carbon components. By the end, these two methods will produce the same result.

Preview

A preview of what you will build:

Prerequisites

Fork, clone and branch

This tutorial has an accompanying GitHub repository called carbon-tutorial-angular that we’ll use as a starting point for each step.

Fork

To begin, fork carbon-tutorial-angular using your GitHub account.

Clone

Go to your forked repository, copy the SSH or HTTPS URL and in your terminal run the two commands to get the repository in your local file system and enter that directory.

git clone [your fork SSH/HTTPS]
cd carbon-tutorial-angular

Add upstream remote

Add a remote called upstream so we can eventually submit a pull request once you have completed this tutorial step.

SSH:
git remote add upstream [email protected]:carbon-design-system/carbon-tutorial-angular.git

Or, if you prefer to use HTTPS instead of SSH with your remotes:

HTTPS:
git remote add upstream https://github.com/carbon-design-system/carbon-tutorial-angular.git

Verify that your forked repository remotes are correct:

git remote -v

Your terminal should output something like this:

origin  [your forked repo] (fetch)
origin  [your forked repo] (push)
upstream    [email protected]:carbon-design-system/carbon-tutorial-angular.git (fetch)
upstream    [email protected]:carbon-design-system/carbon-tutorial-angular.git (push)

Branch

Now that we have our repository set up, let’s check out the branch for this tutorial step’s starting point. Run the two commands:

git fetch upstream
git checkout -b angular-step-1 upstream/angular-step-1

Install Angular CLI

Since we are starting from scratch, we need to first install Angular CLI. Currently you need to install Angular CLI Version 8.x to work through this tutorial.

npm install -g @angular/cli

Create an Angular App

Now that we have our environment set up, starting a new Angular app is easy! If you haven’t set up the environment yet, please do so using the steps provided in Prerequisites (above). We will be using the Angular CLI to create and generate our components. It can also generate services, router, components, and directives.

To create a new Angular project with Angular CLI, just run:

ng new carbon-angular-tutorial

This will create the new project within the current directory. Make sure you do this within the cloned fork of the project. When you get prompted, enter the following.

? Would you like to add Angular routing? Yes
? Which stylesheet format would you like to use? SCSS

This command will install the Angular app with all the configurations needed. Within the project folder carbon-angular-tutorial, the src directory should have the following structure:

carbon-angular-tutorial
...
  ├── src
    ├── app
    │   ├── app-routing.module.ts
    │   ├── app.component.html
    │   ├── app.component.scss
    │   ├── app.component.spec.ts
    │   ├── app.component.ts

Install Carbon

Even though we installed some dependencies while creating the new app, we’ve yet to install the Carbon packages.

  • carbon-components - Component styles
  • carbon-components-angular - Angular components
  • @carbon/icons - Carbon icons
npm install carbon-components carbon-components-angular @carbon/icons

Import carbon-components styles

In src/styles.scss, import the Carbon styles by adding the following to the top of the file:

src/styles.scss
@import '~carbon-components/scss/globals/scss/styles';

Run the app

Now we can run our app for a quick preview inside the browser.

npm start

Your app should now be running with the message: ** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **

Before we start adding components we want to start with an empty project, so delete everything in app.component.html except for the router-outler. We will also have to delete the test that was associated with this code. So in app.component.spec.ts, delete the should render title and should have as title 'carbon-angular-tutorial' test.

Add UI Shell

Next, we’re going to create an Angular component called Header to use with the UI Shell Carbon component. Using Angular CLI we will create this component inside the src/app directory.

ng g component header --lint-fix
Folder structure
src/app/header
├── header.component.html
├── header.component.scss
├── header.component.spec.ts
└── header.component.ts

Import UI Shell

Next we’ll import our Carbon UI Shell components into app.module.ts, app.component.spec.ts and header.component.spec.ts. Set up the file like so:

src/app/app.module.ts
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';


import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
import { HeaderComponent } from './header/header.component';


// carbon-components-angular default imports
import { UIShellModule, IconModule } from 'carbon-components-angular';
src/app/app.component.spec.ts,src/app/header/header.component.spec.ts
import { UIShellModule } from 'carbon-components-angular/ui-shell/ui-shell.module';
src/app/app.component.spec.ts,src/app/header/header.component.spec.ts
TestBed.configureTestingModule({
  declarations: [HeaderComponent],
  imports: [UIShellModule]
});

Import and register icons

Now let’s import the icons from our @carbon/icons package. In app.module.ts, app.component.spec.ts and header.component.spec.ts, we need to import each individual icon we will use and register them with the IconService

src/app/app.module.ts,src/app/app.component.spec.ts,src/app/header/header.component.spec.ts
import Notification16 from '@carbon/icons/es/notification/16';
import UserAvatar16 from '@carbon/icons/es/user--avatar/16';
import AppSwitcher16 from '@carbon/icons/es/app-switcher/16';

In the AppModule class we’ll add a constructor that provides us with an instance of IconService and call registerAll with an array of the icons we need to use.

src/app/app.module.ts,src/app/app.component.spec.ts,src/app/header/header.component.spec.ts
constructor(protected iconService: IconService) {
  iconService.registerAll([
    Notification16,
    UserAvatar16,
    AppSwitcher16
  ]);
}

Then we need to add the template code. Populate header.component.html with:

src/app/header/header.component.html
<ibm-header name="Carbon Tutorial Angular">
  <ibm-header-navigation ariaLabel="Carbon Tutorial Angular">
    <ibm-header-item href="/repos">Repositories</ibm-header-item>
  </ibm-header-navigation>
  <ibm-header-global>