gem-hunter

📦 You are reading the docs for v11, which is in alpha. v11 is a rewrite for React 19, TypeScript, and SLDS 2. Install it with the @alpha tag; a plain npm install still gives you the stable 0.10.x release. Using 0.10.x? See the 0.10.x README and the 0.10.x documentation site. The remaining v11 work is tracked in ROADMAP.md.

@alpha points to v11 pre-releases. Use @latest for the latest stable release. Releases and their notes are listed on the GitHub Releases page.

v11 is not a drop-in upgrade from 0.10.x: some components were removed or renamed. See CHANGELOG.md for the breaking changes.

• SLDS 2 — Styled by the SLDS 2 npm package, with the Cosmos (default) and Lightning Blue themes
• Dark mode — Light, dark, and system color schemes from the SLDS 2 stylesheet
• React 19 — Function components and hooks
• TypeScript — Type definitions ship with the package
• Accessible — Built to WCAG 2.1 AA, with keyboard navigation and screen reader support

npm install @salesforce/design-system-react@alpha

Without the @alpha tag, npm installs 0.10.x. Alpha releases can include breaking changes between versions, so consider pinning the exact version you tested against.

npm 7 and later also installs the peer dependencies: react, react-dom, and @salesforce-ux/design-system, which provides the icons. The stylesheet package, @salesforce-ux/design-system-2, is a regular dependency.

• Found: react@18…: v11 requires React 19.2 or later. Upgrade React, or stay on 0.10.x.

• Found: @salesforce-ux/design-system@…: 11.0.0-alpha.4 and earlier pin this peer dependency to exactly 2.25.0-alpha.2, so a project that already has another version fails to install. Later releases accept any 2.x version from 2.25.0-alpha.2 on. On an affected version, install with --legacy-peer-deps. That flag also skips automatic peer installs, so add React yourself:

  npm install @salesforce/design-system-react@alpha react@^19.2.0 react-dom@^19.2.0 --legacy-peer-deps

• React and React DOM: ^19.2.0
• Node.js: >= 24 (declared in engines; npm warns on older versions)
• A bundler that understands the exports field (Vite, webpack 5, Rollup, esbuild, and so on). The package ships ES modules, CommonJS, and .d.ts files.

Welcome to this community-supported project! This library is the React implementation of the Salesforce Lightning Design System.

• Usage
• Contributing
• Codebase overview

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

function App() {
	return (
		<IconSettings iconPath="/assets/icons">
			<Button label="Hello Button" />
		</IconSettings>
	);
}

Most components also have their own entry point:

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

Known issue: In 11.0.0-alpha.4, ColorPicker, Filter, and Tree have no components/<name> entry point. Import them from @salesforce/design-system-react.

The components render SLDS markup but don't ship CSS. Add an SLDS 2 stylesheet from @salesforce-ux/design-system-2, which installs with this package. Cosmos is the default theme. If your bundler handles CSS imports (Vite, webpack, and so on), import it once at your app's entry point:

import '@salesforce-ux/design-system-2/dist/css/bundled/slds2.cosmos.css';

Without a bundler, serve the package's dist/css folder from your app and link the stylesheet:

<link rel="stylesheet" href="/slds2/bundled/slds2.cosmos.css" />

Here /slds2 is wherever you serve dist/css, e.g. app.use('/slds2', express.static('node_modules/@salesforce-ux/design-system-2/dist/css')).

Note: The stylesheet references a few images (avatar placeholders, Einstein backgrounds) through ../../public/ URLs that @salesforce-ux/design-system-2 2.264.x doesn't include. Vite warns and builds anyway; with webpack, set css-loader's url option to skip those paths. Components that don't use those images are unaffected.

The package's dist/css/bundled/ folder has these stylesheets:

To choose a color scheme, put an slds-color-scheme--* class on <body>:

<body class="slds-color-scheme--system">
	...
</body>

The SLDS 2 stylesheet switches its color tokens based on that class, so the components follow it without any extra props. The Storybook theme toolbar works the same way; see .storybook/preview-decorator.js.

Icons load from external SVG sprite files. Set the sprite folder with <IconSettings>:

import ReactDOM from 'react-dom/client';
import IconSettings from '@salesforce/design-system-react/components/icon-settings';

ReactDOM.createRoot(document.getElementById('root')!).render(
	<IconSettings iconPath="/assets/icons">
		<App />
	</IconSettings>
);

The sprites ship in @salesforce-ux/design-system. Serve that folder from your app:

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

• Node.js 24 (the repo's .nvmrc pins the exact version)
• npm 10 or later

git clone git@github.com:salesforce/design-system-react.git
cd design-system-react
nvm use
npm install
npx playwright install chromium   # for the real-browser test project

CONTRIBUTING.md covers the full workflow, and AGENTS.md lists the commands and pitfalls in one place.

• Build: Vite
• Testing: Vitest + React Testing Library, with a Playwright-driven browser project
• Documentation: Storybook 10
• Language: TypeScript (strict mode)

Components are built to WCAG 2.1 AA:

• Automated testing with axe-core
• Keyboard navigation support
• Screen reader compatibility (JAWS, NVDA, VoiceOver)
• ARIA attributes and roles

Please report any security issues to security@salesforce.com.

Please read CONTRIBUTING.md before submitting pull requests.

• Questions: Post on StackOverflow with the design-system-react tag
• Bugs: Create a GitHub Issue. Please include the package version and whether you're on @alpha or @latest.

• Source code: BSD 3-Clause
• Icons and images: Creative Commons Attribution-NoDerivatives 4.0
• Salesforce Sans font: Font License