1. Installing Carbon

A preview of what you will build:

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

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

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.

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

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

Verify that your forked repository remotes are correct:

Your terminal should output something like this:

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:

We have the repository forked to your GitHub account, cloned down to your machine, and the starting branch checked out. Next, install the Vue app’s dependencies with:

After the dependencies are installed, you can start the app with:

Your default browser should open up with an empty page that says: Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.

OK. So we made a small change to the Vue CLI generated app replacing the HelloWorld component and replaced it with our own message and swapped out the favicon.

Even though we installed existing dependencies, we’ve yet to install the Carbon packages.

Stop your development server with CTRL-C and install Carbon dependencies with:

If you check out the file package.json, you’ll notice a few dependencies beyond those listed above. These were installed as part of the project creation using the Vue CLI. These include:

NOTE: We could have installed these separately but using the CLI to set this up for us ensures a good base config for these dependencies.

To avoid having to add the ~ prefix when importing SCSS files from node_modules, create a .env file at the project root that contains:

For the Windows operating system, use:

Then, start the app again. If your app’s currently running, you’ll need to restart it for the new environment variable to be used.

The app looks as it did before. Next, let’s add Carbon styling.

In the src directory, create a sub-directory styles and add a new file _carbon.scss to it. Then in App.vue edit the style tag to import it.

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

This will take a moment for the Sass to compile. Once compiled, you’ll notice that the Carbon base styling is applied (IBM Plex Sans font family, font size, weight, colors, etc.)

Because any change to _carbon.scss will re-compile all of the Carbon Sass, avoid making changes here unless instructed to do so. it is better to make them in the component files or a separate file if needed.

Next we’ll create a Carbon Button to test that our dependencies are working properly.

After the other imports in main.js and before the Vue instance is created add the following.

This is a quick way to pull in all @carbon/vue components and register them for use in your project. Individual components can be imported to a project or component.

e.g. Instead of modifying src/main.js we could have added the following to src/App.vue:

See the Carbon Vue Components documentation for other ways to load components from @carbon/vue components.

In this tutorial we will stick to importing all of the components at once so we can focus on our use of @carbon/vue.

Now open the App.vue component and replace:

with:

or

Congratulations, you’ve imported your first component! You should see a Carbon styled button on the page.

NOTE: In this tutorial you can use either tag format. The Vue style guide recommend sticking to either Pascal or kebab case. The examples from here will use Pascal case for file and component names with kebab case in the HTML.

Next we’re going to create a Vue component called TutorialHeader to use with the UI Shell Carbon component. Create a new directory src/components. In the src/components directory, create TutorialHeader directory. Create the following files inside src/components/TutorialHeader:

In src/components/TutorialHeader/index.js, import and export our TutorialHeader component like so:

If you are using VSCode then you might want to add the following snippet which will when you type ‘index’ generate an index file for you based on the folder name.

You can also use the following to create a skeleton component. To use this one, start typing the word template in your template file and it will generate a file, making assumptions based on the component file name.

OK, back to using Carbon components. Let’s make use of our Carbon UI Shell components in TutorialHeader.vue. Set up the file like so:

Now let’s import the icons from our @carbon/icons-vue elements package. After the closing template tag in the TutorialHeader.vue file, we need to import each individual icon we will use.

Then we need to add content to the header-global slot where we will use our icons. These represent actions in the header a user can make. Replace:

With:

Next we’ll render our UI Shell by importing our Tuto