Skip to content
Salesforce Lightning Design System for React
JavaScript Other
Branch: master
Clone or download

Latest commit

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add how to release a tag to 1st time PR bot Feb 23, 2019
.jest
.storybook fixing the MIME type error in loading override CSS file in storybook Feb 2, 2020
assets remove temp rtl svg now that slds has been upgraded Jul 3, 2019
components Merge pull request #2492 from garygong/row-custom-class Apr 22, 2020
docs Merge remote-tracking branch 'upstream/master' into dennismphil/react… Aug 26, 2019
eslint-plugin Eslint rules fix May 21, 2019
icons `@salesforce-ux/icons` update from 7.34.0 to 9.27.0 - added new icons Jul 16, 2019
preset eslint-plugin: Add license info Sep 15, 2018
scripts Update prepare-components script Nov 16, 2019
styles fixed issue with being able to select "disabled" tabs Sep 20, 2019
tests readme typo fix Feb 12, 2020
utilities Fix DeepScan warnings Feb 25, 2020
.editorconfig Promote line length of 80 in editors Feb 13, 2018
.eslintignore Make test process less opaque Jan 30, 2018
.eslintrc.js
.gitignore fixed conditional issues and wrapped items with canUseDom and canUseE… Apr 18, 2019
.prettierignore Makes Prettier ignore more directories generated during testing. Oct 17, 2018
.prettierrc.json Move prettier config to external file Feb 14, 2018
.snyk Update snyk Aug 2, 2019
.travis.yml TravisCI: Run a11y tests first Sep 11, 2019
CONTRIBUTING.md merged in master Aug 27, 2019
LICENSE.txt Update license to two lines Apr 6, 2017
Procfile Add authentication May 24, 2016
README.md Add Kevin to Key Contributors Jan 9, 2020
RELEASENOTES.md
app.js Improve Storyshots tests experience May 17, 2018
app.json Run prettier on JSON Feb 13, 2018
babel.config.js Upgrade Storybook, Webpack, add a11y testing Jul 22, 2019
karma.conf.js tweaks to remove 404 issues from karma Oct 23, 2019
package-lock.json Clean up for release Apr 22, 2020
package.json Bump package version Apr 22, 2020
webpack.config.dist.js Ad eslint ignore rules for functional programming Sep 9, 2019
webpack.config.js Upgrade Storybook, Webpack, add a11y testing Jul 22, 2019
webpack.config.test.js removing all warnings from CI Oct 23, 2019

README.md

Lightning Design System for React

Accessible, localization-friendly, presentational React components

Build Status DeepScan grade Known Vulnerabilities Join the chat at https://gitter.im/salesforce/design-system-react Monthly NPM downloads

Install

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

Getting Started

Welcome to this community-supported 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 is tested with React 16 and has a stable API despite its version number. Please polyfill this library in order to meet your target environment needs.

Usage

Quick Setup (ES6 and CJS modules)

For a no hassle setup and compatibility with Create React App, transpiled ES6 and CommonJS module versions have been included within the NPM package. If using this setup, please re-write the import statement in the documentation site examples. Use the following named import syntax to access the transpiled 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"]
}

The current preset version is only compatible with Babel 6. Please see this issue comment for Babel 7.

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.

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/design-system/assets/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')
)

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.

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
cd design-system-react
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.

Accessibility

Audit conducted in November, 2019 on all current component examples not intended solely for testing by Salesforce Marketing Cloud (MC) Accessibility Specialist and project team.

  • Methods: Automated testing with axe; Manual testing with keyboard, JAWS, and NVDA
  • Results: 100% accessibility

Quarterly audits will be conducted beginning Feb 1, 2020 on any new or updated components by MC Accessibility Specialist.

  • Methods: Automated testing with axe; Manual testing with keyboard, JAWS, and NVDA
  • Goal: 100% accessibility

Project team will conduct internal accessibility testing in development process for new and updated components.

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.

Security

Please report any security issue to security@salesforce.com as soon as it is discovered. This library limits its runtime dependencies in order to reduce the total cost of ownership as much as can be, but all consumers should remain vigilant and have their security stakeholders review all third-party dependencies.

Contributors

Thank you to all the contributors to this one of many open source projects at Salesforce, but special thanks to the following:

Active Key Contributors

Former Key Contributors

Licenses

You can’t perform that action at this time.