Design System for React

Accessible, localization-friendly, presentational React components

Getting Started

Welcome to the project! 👋 This library is the React implementation of the Salesforce Lightning Design System. It has been tested with React >=15.4.1 <16 and is stable despite its version numbers. A 1.0 will be released soon.

ECMAScript 6, CommonJS and `create-react-app`

It is highly recommended that you npm install the -es suffixed tag and import individual components. You will need a stage-1 and higher proposed features transpiler (stage-1 Babel preset or review our .babelrc) and include transpiling the node_modules/design-system-react folder in your configuration. The non-suffixed package is a CommonJS build that should allow dropping dead code, but not tree-shaking.

create-react-app and any environment that does not transpile or let you transpile ES6 code within the node_modules folder is not compatible with the -es suffixed tag. Please use the non-suffixed CommonJS tag until an NPM module is published that is compatible with create-react-app.

Local development Storybook and in-browser test server

npm install
npm start
open http://localhost:9001 http://localhost:8001

SLDS Icons

Prior to v0.7.0, SLDS icons were bundled with the JavaScript. The 400KB+ icons bundle from SLDS is no longer included. You will need to download the SLDS CSS and icons separately.

Serve icons publically

Typically, scripts should be downloaded in the background without blocking the DOM. With React, this works best with server side rendering. SLDS recommends placeholder stencils while scripts are initializing if the HTML cannot be served immediately. If you can serve the HTML, then icon SVGs should not be bundled and served like any other file. Set a path context for all child components with <IconSettings> at the top of your render tree:

import IconSettings from 'design-system-react/components/icon-settings';

ReactDOM.render(
  <IconSettings iconPath="/assets/icons">
    <MyApp />
  </IconSettings>,
  document.getElementById('app')
)

// `/assets/icons` wil be prepended to `/standard-sprite/svg/symbols.svg#account` within the SVG path
<svg aria-hidden="true" class="slds-icon">
  <use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons/standard-sprite/svg/symbols.svg#account"></use>
</svg>

// ExpressJS example
app.use('/assets/icons', express.static('node_modules/@salesforce-ux/icons/dist/salesforce-lightning-design-system-icons/'));

Bundle icons

If you use a module bundler, like Webpack, you can import the individual sprite files and assign them to the <IconSettings> sprite properties. Your SVG images will be bundled with your scripts and block the DOM from rendering until the script file is loaded.

import IconSettings from 'design-system-react/components/icon-settings';

import standardSprite from '@salesforce-ux/design-system/assets/icons/standard-sprite/svg/symbols.svg';
...
...

ReactDOM.render(
  <IconSettings standardSprite={standardSprite}>
    <MyApp />
  </IconSettings>,
  document.getElementById('app')
)

Example

Add the following line to your package.json devDependencies and run npm install.

# package.json

"design-system-react": "git+ssh://git@github.com:salesforce/design-system-react.git#v[VERSION]",

The bundled files are provided only for convenience.

design-system-react.min.js (700KB+) - includes icons in the JavaScript
design-system-react-components.min.js (~400KB) - no icons.

Import and use only the components you need:

import Tooltip from 'design-system-react/components/popover-tooltip';
import Icon from 'design-system-react/components/icon';
import IconSettings from 'design-system-react/components/icon-settings';

<IconSettings iconPath="/assets/icons">
  <Tooltip
    align="top"
    content={<span>Here is more information.</span>}
  >
    <a href="javascript:void(0)">
      <Icon assistiveText="More Info" category="utility" name="info" className="slds-icon-text-default" />
    </a>
  </Tooltip>
</IconSettings>

Contributing to the code base

Please read the CONTRIBUTING.md and Test README first. Then, create an issue to tell others you are working on a bug. If you would like to contribute a new component, create an issue with a list of proposed props to discuss with maintainers. Issues not addressed with pull requests may be closed eventually. Check out who's contributing to the project.

Licenses

Source code is licensed under BSD 3-Clause
All icons and images are licensed under Creative Commons Attribution-NoDerivatives 4.0
The Salesforce Sans font is licensed under our font license

Got feedback?

If you have support questions, please post a question to StackOverflow and tag with design-system-react. If you find any bugs, create a GitHub Issue.

mkelley33/design-system-react