Using React components

We strongly recommend using the React versions of our components. React allows for more complex, interactive components like Tabs or VerticalNav, and many of our React components have built-in accessibility optimizations.

The examples below assume you've installed the design system using NPM and have already setup your build system for React.

Named imports

Components can be imported from the package entry point using the syntax below.

import { Button, TextField } from '@cmsgov/design-system';

The @cmsgov/design-system package provides an ES modules version of our code to support Webpack 4's tree shaking optimizations. Our package is configured to use the modules property to let bundlers know to resolve imports from @cmsgov/design-system to the ES modules version when preferred. Read more about ESM in Webpack's documentation, or from Rollup's proposal.

Individual imports

Components can also be imported from their individual export file. This method carries no risk of including unused or extra code, as you are only importing from a specific file.

import Button from '@cmsgov/design-system/dist/components/Button/Button';
import TextField from '@cmsgov/design-system/dist/components/Button/TextField';

Usage

After importing the React component, tell React to render the component in the DOM:

ReactDOM.render(
  <Button
    variation="primary"
    className="custom-btn"
    onClick={() => alert('Button clicked!')}>
    Button react component
  </Button>
  document.querySelector('#app'),
);

More React prop documentation, examples, and guidance can be found on component documentation pages.

Using CSS components

If your project doesn't use React, we provide a HTML/CSS-only version of our components. This includes styles for every component in the library, but you’ll be responsible for writing the correct markup and updating classes and DOM attributes in response to user events.

This example assumes you've already added design system styles via CSS or Sass.

<div class="ds-c-alert ds-c-alert--warn">
  <div class="ds-c-alert__body">
    <h3 class="ds-c-alert__heading">Warning status</h3>
    <p class="ds-c-alert__text">Alert warning body text</p>
  </div>
</div>

More HTML/CSS examples and guidance can be found on component documentation pages.

Examples

Additional examples of the design system in use can be viewed on GitHub. These projects demonstrate the various ways you can incorporate the design system into your development process and various use cases.

• Webpack example
• CSS-only example

Need help or ran into an issue?

If you're having trouble installing or setting up the design system, or if you think you've found a bug, feel free to open an issue on GitHub.