Salesforce Lightning Design System for React is the React implementation of the Salesforce Lightning Design System.
This repository represents a test implementation of Salesforce Lightning components with UXPin Merge Technology. To make this implementation few changes were introduced to Salesforce Lighting:
- Every component is now stored in an individual directory – e.g.
./components/accordion/accordion-panel. - In order to preserve all the component imports –
index.jsfiles were introduced. Index files are only importing and exporting a component in a given directory. - Preset directories were introduced. Preset files tell UXPin Merge how to initially render every component. E.g.
.componnets/accordion/presets/0-default.jsx(both name of the directory –presetsand name of the file0-default.jsxare UXPin Merge conventions)
Merge is a revolutionary technology that lets users import (and keep in sync) coded React.js components from GIT repositories to UXPin editor. The imported components are 100% identical to components used by developers during the development process. It means that components are going to look and, function (interactions, data) identical to the real product experienced by the users.
UXPin is a leading code–based design platform.
Merge is currently only available for selected beta users.
- Fork this repository and clone it to your computer.
- Install dependencies with
npm install - Log in to your UXPin beta account (approved for alpha and beta tests by UXPin Inc.)
- Start Merge dev environment with
npm run uxpin:experiment
If you wish to push Salesforce Lightning React components to your UXPin account or set-up a continues integration with a CI server - contact UXPin on Merge alpha Slack community.
| Component | SF DS React Link | Components Status in Merge |
|---|---|---|
| Accordion | Accordion | ✅ Full Support |
| Alerts | Alerts | ✅ Full Support |
| Avatars | Avatars | ✅ Full Support |
| BrandBand | Brand Band | ✅ Full Support |
| Breadcrumbs | Breadcrumbs | ✅ Full Support |
| ButtonGroup | Breadcrumbs | ✅ Full Support |
| Button | Buttons | ✅ Full Support |
| Card | Cards | ✅ Full Support |
| Checkbox | Checkboxes | ✅ Full Support |
| ColorPicker | Color Pickers | ✅ Full Support |
| Combobox | Comboboxes | ✅ Full Support. Additional interactivity added in CombovoxInteractive component. |
| DataTable | DataTables | Not supported yet |
| Datepicker | Datepickers | ✅ Full Support |
| DropdownMenu | Dropdown Menus | ✅ Full Support |
| Icon | Icons | ✅ Full Support |
| Illustration | Illustrations | ✅ Full Support |
| Input | Inputs | ✅ Full Support |
| MediaObject | Media Objects | ✅ Full Support |
| Modals | Modals | 🔻 Not Supported. Issues with absolutely positioned elements. |
| PageHeader | Page Headers | 🔻 Not Supported. Issues with absolutely positioned elements. |
| PillContainer | Pill Container | ✅ Full Support |
| Pill | Pills | ✅ Full Support |
| Popover | Popovers | ✅ Full Support |
| ProgressIndicator | Progress Indicators | ✅ Full Support. Additional interactivity added in CombovoxInteractive component. |
| ProgressRring | Progress Rings | ✅ Full Support |
| RadioButtonGroup | Radio Button Groups | ✅ Full Support |
| RadioGroup | Radio Groups | ✅ Full Support |
| Radio | Radios | ✅ Full Support |
| Slider | Slider | ✅ Full Support |
| Spinner | Spinners | ✅ Full Support |
| Spinner | Spinners | ✅ Full Support |
| SplitView | Split Views | Not supported yet |
| StatefulButton | Stateful Buttons | ✅ Full Support |
| Tabs | Tabs | ✅ Full Support |
| Textarea | Textareas | ✅ Full Support |
| Timepicker | Timepickers | ✅ Full Support |
| Toast | Toasts | ✅ Full Support |
| Tooltip | Tooltips | ✅ Full Support |
| Tree | Trees | ✅ Full Support |
| VerticalNavigation Vertical Navigation | Not supported yet. | |
| AppLauncher | App Launcher | ✅ Full Support |
| GlobalHeader | Global Header | 🔻 Not Supported. Issues with automatically rendered – not compatible with Merge |
The recommended approach to integrating React.js components with UXPin is via Continues Integration server (Circle CI, Travis...). This approach provides an opportunity to establish a real single source of truth for design and development.
After the integration with a CI server every commit to master can (if this is how your CI is configured) automatically update library in UXPin.
This repository consits of an example of integration with Circle CI. If you wish to reuse it follow these steps:
- Make sure that you forked this repository.
- Go to https://circleci.com and sign-up for an account with your Github credentials.
- Start a new project and track your fork of this repository.
- Go into your UXPin account, enter UXPin editor (in any project).
- While inside of UXPin editor open Design Systems Libraries panel and create a new library. Copy the library token (keep it secure it provides access to your library!)
If you're not seeing the screen above – contact your account manager. You're not in Merge Beta group yet.
- Go into settings of your project in Circle CI. Enter section
Environment Variablesand click onAdd new variable. - Name the new variable
UXPIN_AUTH_TOKENand pass your token copied from the UXPin library (#5) as its value.
That's it! The next change in the master branch of your fork will automatically trigger Circle CI and send the newest version of your components to UXPin.
Integration with CI server leads to a powerful workflow, with that however comes couple of dangers, so please be aware of them!
⚠️ Don't share your UXPin authorization token with anyone. It leads straight to your design system library in UXPin. Keep the token safe in the CI app!⚠️ Don't keep your UXPin authorization token in any file checked into your git repository.⚠️ Treat contributing to Master branch just like deploying production code. Any change will be automatically reflected in the UXPin library and projects. If you want to experiment with components – start a new branch and use Merge dev environment – experiment mode (in this repository launched vianpm start)
$ npm install @salesforce-ux/design-system @salesforce/design-system-react
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 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
- Getting started
- Documentation and interactive examples
- Contributing
- Codebase overview
- Create React App setup
- Browser compatibility and polyfills
- Usage with Webpack
- Open Sourcing Design System React - Medium article
For a no hassle setup and compatibility with Create React App v1, a CommonJS version has 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 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 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" />
{
"presets": ["@salesforce/babel-preset-design-system-react"]
}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.
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/'));
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')
)
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 JavaScriptdesign-system-react-components.min.js(~400KB) - no icons.
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.
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.
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.
Thank you to all the contributors to this one of many open source projects at Salesforce, but special thanks to the following:
- @davidlygagnon David Ly-Gagnon
- @futuremint David Woodward
- @garygong Gary Gong
- @interactivellama Stephen James
- @donnieberg Donielle Berg
- @tweettypography David Brainer
- @ivanbogdanov Ivan Bogdanov
- 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