Skip to content

Latest commit

 

History

History
154 lines (105 loc) · 5.17 KB

getting-started.stories.mdx

File metadata and controls

154 lines (105 loc) · 5.17 KB
Raw

import LinkTo from "@storybook/addon-links/react";

Getting started with Carbon

Get up and running with the Carbon library and start developing your application with Carbon integration.

Contents

Installation

Peer Dependencies

Installation

Carbon is available as an npm package, install it into your project with:

npm install carbon-react

Peer Dependencies

You will need to install the following dependencies in your project, these are peer-dependencies of carbon-react and are required.

npm install @sage/design-tokens@^2.3.0 react@^16.14.0 react-dom@^16.14.0 styled-components@^4.4.1

There is a peer dependency on draft-js any project intending to use either the TextEditor or Note components is required to install it as well.

npm install draft-js@^0.11.5

Global stylesheet

We recommend using our global stylesheet which could be imported:

import GlobalStyle from 'carbon-react/lib/style/global-style';

then the GlobalStyle component could be placed next to the content of the app:

  <App>
    <GlobalStyle />
    .
    .
    .
  </App>

Fonts

Carbon requires the Sage UI and CarbonIcons fonts to display correctly. These will not be automatically loaded by Carbon, so you will be required to load these into your application yourself.

Your build system must support CSS and file loading for this to work, e.g. webpack with css-loader and file-loader. This is pre-configured if you are using create-react-app, but it is possible to use other bundling solutions such as parceljs if you wish.

The font face definitions for both fonts are included in Carbon and can be directly imported into your code using one of the following snippets:

Using CSS
/* Import Sage UI and CarbonIcons fonts */
@import "~carbon-react/lib/style/fonts.css";
Using JavaScript
// Import Sage UI and CarbonIcons fonts
import "carbon-react/lib/style/fonts.css";

Note the Sage UI font files themselves are loaded from the @sage/design-tokens library. If this has not been installed in your project beforehand, text will be rendered in the browser's default sans-serif font.

React and React DOM

React and React DOM are imported from the React library, which forms the basis for Carbon's components.

import React from "react";
import ReactDOM from "react-dom";

Theming and Design Tokens

Carbon supports two theming systems - the latest which uses Design Tokens in form of CSS custom properties maintained by designers, and legacy themes which use old theme properties from the ThemeProvider from the styled-components library. Currently both systems are being supported to aid projects using older versions of Carbon with upgrading.

The themes available in Carbon include:

  • sage - the latest theme which uses Design Tokens in form of CSS custom properties. Note this theme requires installation of @sage/design-tokens library, otherwise styles fallback to the old mint theme for compatability.
  • mint, aegean and none - legacy themes that use old theme properties consumed by ThemeProvider.

Carbon Provider

Carbon provides the Carbon Provider component that uses the ThemeProvider from the styled-components library to supply theme styles to your components. Themes are defined within the Carbon library and can be imported like the following snippet. mintTheme is provided by default.

import CarbonProvider from "carbon-react/lib/components/carbon-provider";
import sageTheme from "carbon-react/lib/style/themes/sage";

Default mintTheme:

<CarbonProvider>Children</CarbonProvider>

The latest sageTheme:

<CarbonProvider theme={sageTheme}>Children</CarbonProvider>

Quickstart

A basic project index.js file would resemble this example.

import React from "react";
import ReactDOM from "react-dom";
import CarbonProvider from "carbon-react/lib/components/carbon-provider";
import GlobalStyle from "carbon-react/lib/style/global-style";
import sageTheme from "carbon-react/lib/style/themes/sage";
import "carbon-react/lib/style/fonts.css";
import Box from "carbon-react/lib/components/box";
import Button from "carbon-react/lib/components/button";

const App = (props) => {
  return (
    <CarbonProvider theme={sageTheme}>
      <GlobalStyle />
      <Box margin="0 25px">
        <Button>Hello Carbon</Button>
        <p>Please remember to select the appropriate version of Carbon.</p>
      </Box>
    </CarbonProvider>
  );
};

ReactDOM.render(<App />, document.getElementById("app"));

This can also be found in our Codesandbox template.