Skip to content

Latest commit

 

History

History
205 lines (174 loc) · 6.19 KB

getting-started.stories.mdx

File metadata and controls

205 lines (174 loc) · 6.19 KB
Raw

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 react@^16.12.0 react-dom@^16.12.0 i18n-js@^3.0.1 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

CDN

carbon-react requires the Lato and CarbonIcons fonts to display correctly.

To embed the Lato font, copy the code below into the <head> of your HTML.

<link href="https://fonts.googleapis.com/css2?family=Lato:wght@400;700;900" rel="stylesheet">
Self Hosted

Please be aware that the Google Fonts CDN provides the optimal stylesheet based on the browser user-agent string to limit "flash of unstyled text". It's important that you fully understand the technical considerations before hosting any font yourself.

The Lato font can be downloaded from Google Fonts.

  @font-face {
    font-family: 'Lato';
    src: url('./fonts/Lato-Regular.eot') format('embedded-opentype');
    src: url('./fonts/Lato-Regular.svg') format('svg');
    src: url('./fonts/Lato-Regular.woff') format('woff');
    src: url('./fonts/Lato-Regular.ttf') format('truetype');
    font-weight: normal;
    font-style: normal;
  }

Note: You'll need to define a @font-face for each font-weight.

The path to the CarbonIcons font is carbon-react/lib/style/fonts/carbon-icons-webfont.woff.

@font-face {
  font-family: 'CarbonIcons';
  src: url('./node_modules/carbon-react/lib/style/fonts/carbon-icons-webfont.woff') format("woff");
  font-weight: normal;
  font-style: normal;
}

If you are using webpack, you can use file-loader or url-loader to bundle the fonts with your application. url-loader will allow any assets under a given limit to be embedded as a dataURL in base64 and reduce network requests; file-loader can be used for any asset over the limit.

Example of webpack.config.js

module.exports = {
  ...
  module: {
    rules: [
      ...
      {
        test: /\.(woff|woff2|eot|ttf|otf|svg)$/,
        use: [{
          loader: 'url-loader',
          options: {
              limit: 8192,
            }
        }]
      },
      {
        test: /\.(woff|woff2|eot|ttf|otf|svg)$/,
        use: [{
          loader: 'file-loader',
          options: {
            name: '/[name].[ext]',
            outputPath: 'fonts/'
          }
        }]
      }
      ...
    ]
  }
  ...
};

If you are not using webpack, you will need to ensure that the font files are available in your build and that the @font-face use the correct URL's.

You can move it to your build folder as part of your build.

mkdir -p dist/fonts
cp ./node_modules/carbon-react/lib/style/fonts/carbon-icons-webfont.woff ./dist/fonts/

Or publish it to a CDN such as Amazon S3.

aws s3 sync ./node_modules/carbon-react/lib/style/fonts/carbon-icons-webfont.woff s3://example.com/fonts/

While not required, we also recommend using webfontloader to control the loading behaviour and avoid a "flash of unstyled text". webfontloader adds CSS classes to the <body> giving you finer control over the blocking behaviour.

WebFont.load({
  custom: {
    families: ['CarbonIcons', 'Lato']
  }
});

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

Carbon uses the ThemeProvider from the styled-components library to supply theme styles to your components. Themes are define within the Carbon library.

import { ThemeProvider } from "styled-components";
import mintTheme from "carbon-react/lib/style/themes/mint";
 <ThemeProvider theme={mintTheme}>
  Children
 </ThemeProvider>

AppWrapper

This component wraps all components within the width constrains of your application.

<AppWrapper>
  Children
</AppWrapper>

You should refer to our Storybook documentation for details.

Quickstart

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

import React from "react";
import ReactDOM from "react-dom";
import { ThemeProvider } from "styled-components";
import mintTheme from "carbon-react/lib/style/themes/mint";
import "carbon-react/lib/utils/css";
import AppWrapper from "carbon-react/lib/components/app-wrapper";
import Button from "carbon-react/lib/components/button";

const App = props => {
  return (
    <ThemeProvider theme={mintTheme}>
      <AppWrapper>
        <Button>Hello Carbon</Button>
        <p>
          Please remember to select the appropriate version of Carbon.
        </p>
      </AppWrapper>
    </ThemeProvider>
  );
};

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

This can also be found in our Codesandbox template.