JavaScript Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github Add stale issue bot May 3, 2018
.storybook-based-tests Make test process less opaque Jan 30, 2018
.storybook Add a11y panel to storybook May 3, 2018
components Merge pull request #1385 from interactivellama/datatable-header-cell-… May 24, 2018
docs Add npm install to create react setup readme May 9, 2018
icons Clean up for release Nov 8, 2017
preset Make preset modules false Mar 2, 2018
scripts Improve Storyshots tests experience May 17, 2018
styles Run Prettier on markdown files Dec 29, 2017
tests DataTable: Move header cells to subrenders May 23, 2018
utilities Fixes #1388 May 18, 2018
.babelrc Spacing fix for .babelrc May 9, 2018
.editorconfig Promote line length of 80 in editors Feb 13, 2018
.eslintignore Make test process less opaque Jan 30, 2018
.eslintrc.json Merge branch 'master' of github.com:salesforce/design-system-react in… Feb 14, 2018
.gitignore Add visual diff images to gitignore May 18, 2018
.prettierignore Move prettier config to external file Feb 14, 2018
.prettierrc.json Move prettier config to external file Feb 14, 2018
.travis.yml Set npm audit to false temporarily May 8, 2018
CONTRIBUTING.md Clarify new component contribution section Apr 25, 2018
LICENSE.txt Update license to two lines Apr 6, 2017
Procfile Add authentication May 24, 2016
README.md Add Create React Setup readme May 9, 2018
RELEASENOTES.md Release patch Apr 27, 2018
app.js Improve Storyshots tests experience May 17, 2018
app.json Run prettier on JSON Feb 13, 2018
karma.conf.js Update karma test runner Feb 14, 2018
package-lock.json Merge branch 'master' into upgrade_react_modal May 21, 2018
package.json Merge branch 'master' into upgrade_react_modal May 21, 2018
webpack.config.dist.js Add commas to end of multiline iterables Feb 5, 2018
webpack.config.js Add commas to end of multiline iterables Feb 5, 2018
webpack.config.test.js Add clarity to browser tests scripts Feb 14, 2018

README.md

Design System for React

Accessible, localization-friendly, presentational React components

Build Status DeepScan Grade

Install

$ npm install @salesforce-ux/design-system @salesforce/design-system-react

Getting Started

Welcome to the project! 👋 This library is the React implementation of the Salesforce Lightning Design System. This library has a peer dependency on @salesforce-ux/design-system, react, and react-dom. It has been tested with React >=15.4.1 <16 and is stable despite its version number. Please polyfill this library in order to meet your target environment needs.

Usage

Quick Setup (CommonJS)

For a no hassle setup and compatibility with Create React App v1, a CommonJS version has been included within the NPM package to allow usage without transpiling. Use the following named import syntax to access CommonJS components from /lib/index.js:

import { Button } from '@salesforce/design-system-react';

<Button label="Hello Button" />

Please view Create React App Setup for more information on using this library with Create React App.

Advanced (Source code)

Advanced usage requires that your babel presets are set up correctly. create-react-app and environments that do not transpile code within node_modules are not compatible with the component import below. All the examples on the documentation site use this syntax. You can use the Babel preset, @salesforce/babel-preset-design-system-react, to get started. This preset will keep Babel compatible with Design System React and allow ES6 module benefits such as tree-shaking. This library is not browser-ready and should be polyfilled to your target environment.

import Button from '@salesforce/design-system-react/components/button';

<Button label="Hello Button" />

Transpile with .babelrc settings

{
	"presets": ["@salesforce/babel-preset-design-system-react"]
}

Styling

This library does not contain any Cascading Style Sheets (CSS). You will need to add <link rel="stylesheet" type="text/css" href="/node_modules/@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.min.css" /> to your page and serve that file from a publicly available folder.

Icon Usage

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 publicly

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 '@salesforce/design-system-react/components/icon-settings';

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

// `/assets/icons` will 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 let your module bundler manage SVG sprite file paths and send that path into <IconSettings>. This requires configuring your module bundler to manage your public assets.

import IconSettings from '@salesforce/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')
)

Bundled script files are provided only for convenience. Do not use in production.

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

Contributing to the code base

Clone and develop locally with Storybook and in-browser tests

git clone git@github.com:salesforce/design-system-react.git
npm install
npm start
open http://localhost:9001 http://localhost:8001

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

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.