Typography
Type is a core part of any offering and critical to how brands express and communicate throughout any experience. Use the Carbon type package to leverage IBM Plex and create effective typography across your products more easily.
Get started
To install @carbon/type in your project, you will need to run the following
command using npm:
npm install -S @carbon/type
If you prefer Yarn, use the following command instead:
yarn add @carbon/type
Usage
The @carbon/type package enables you to use typography from the IBM Design
Language, including the type scale and fonts, along with typography design
tokens from the Carbon Design System. It also comes with opinionated defaults
for type styles on common elements like h1, h2, p, etc.
You can use this package by writing the following:
@use '@carbon/type';// Include type reset@include type.reset();// Include default type styles, targets h1, h2, h3, etc@include type.default-type();// Include utility classes for type-related properties@include type.type-classes();
Type classes
The type-classes mixin will output a collection of utility CSS that you can
use to style a given HTML element with type-related styles.
In particular, you can use the following classes:
| Class | Description |
|---|---|
.cds--type-{font-family} | Set the font-family property for the given font. This can include mono, sans, sans-condensed, sans-arabic, sans-devanagari, sans-hebrew, sans-jp, sans-kr, sans-thai-looped, sans-thai, serif |
.cds--type-{font-weight} | Set the font-weight property |
.cds--type-italic | Set the font-style property to italic |
.cds--type-{token} | Style the HTML element with the given type token |
Type styles
Instead of using a type scale, @carbon/type provides tokens that represent
what we call type styles. These tokens have a variety of properties for styling
how text is rendered on a page.
You can find a full reference of the type styles that are available on the Carbon Design System website .
You can include a token in your Sass file by writing:
@import '@carbon/type/scss/styles';@include type-style('productive-heading-01');
In addition, if the type style you are using has a fluid style then you can pass
in true as the second argument to type-style to enable fluid styles. For
example:
@import '@carbon/type/scss/styles';@include type-style('token-name', true);
Font-face
@carbon/type supports three font-face definitions that you can use to add IBM
Plex to your project. These font-face definitions include support for:
- IBM Plex Mono
- IBM Plex Sans
- IBM Plex Serif
For most projects, only IBM Plex Mono and IBM Plex Sans is necessary. We also provide IBM Plex Serif if you are building an editorial or marketing project.
These font-face definitions are pulling the above fonts from Google Fonts. As a
result, they are not intended to be used as a production asset for your project.
While you can depend on these for bootstrapping your project, we highly
recommend using the fonts from the @ibm/plex package and hosting them on a
global CDN.
You can include each font-face definition by including the corresponding file and calling its mixin. For example, if you wanted to include IBM Plex Mono in your project you would write the following in your Sass file:
@import '@carbon/type/scss/font-face/mono';@include font-face-mono();
Similarly, you can include IBM Plex Sans and IBM Plex Serif by writing:
@import '@carbon/type/scss/font-face/mono';@import '@carbon/type/scss/font-face/sans';@import '@carbon/type/scss/font-face/serif';@include font-face-mono();@include font-face-sans();@include font-face-serif();
Type classes
The recommended way to style your application will be to use our type styles. However, we also offer helper CSS classes for specific use-cases. These are also helpful when quickly prototyping a project.
You can include type classes in your project by writing the following in your Sass file:
@import '@carbon/type/scss/classes';
| Selector | Description |
|---|---|
.cds--type-mono | Specify the font face as IBM Plex Mono |
.cds--type-sans | Specify the font face as IBM Plex Sans |
.cds--type-serif | Specify the font face as IBM Plex Serif |
.cds--type-light | Specify the font weight as light (300) |
.cds--type-regular | Specify the font weight as regular (400) |
.cds--type-semibold | Specify the font weight as semibold (600) |
.cds--type-italic | Specify the font style as italic |
.cds--type-<type-style> | Set styles for the given type style |
Font family
@carbon/type provides the font stacks for all the IBM Plex fonts available.
You can access the font family information by including the following import in
your Sass file:
@import '@carbon/type/scss/font-family';
The font stacks are available under the $font-families variable. You can also
access a specific font family by using the font-family function by doing:
.my-selector {font-family: font-family('mono');}
You can also use the font-family mixin to automatically set the font-family
property for you:
.my-selector {@include font-family('mono');}
You can see all the available font families in $font-families .
Reset
An optional type reset is provided under the type-reset mixin. You can include
this mixin by writing the following in your Sass file:
@import '@carbon/type/scss/reset';@include type-reset();
This reset sets some top-level properties on html and body, namely
font-size, font-family, and some text-rendering options. We also map the
strong tag to the semibold font weight.
Type scale
A type scale is provided through the $type-scale variable and corresponding
type-scale function and mixin. However, for specifying type styles, the
recommendation is to use type styles .
If you are looking to use the type scale, you can include all the scale-related utilities and variables by writing the following in your Sass file:
@import '@carbon/type/scss/scale';
You can access a specific step in the type scale by using the type-scale
function:
@import '@carbon/type/scss/scale';.my-selector {font-size: type-scale(1);}
There is also a type-scale mixin that will set font-size for your directly:
@import '@carbon/type/scss/scale';.my-selector {@include type-scale(1);}