Developing with Salt

Learn how to use Salt’s UI components in your React web applications.

To start developing with Salt, you should:

• Be familiar with React and web development fundamentals (such as HTML, CSS and JavaScript).
• Have Node.js (version 22 or later) installed on your system.
• Create a React (version 16.14 or later) web application project. For new projects, see the React docs for Creating a React App.

The three main packages you’ll need are:

• @salt-ds/core contains production-ready UI components.
• @salt-ds/theme contains the CSS for Salt’s themes.
• @salt-ds/icons contains SVG-based icons.

Install all three in one go:

To install with yarn or another package manager, run the equivalent command. Salt ships additional packages for specific use cases—including @salt-ds/lab for experimental components—which you can add as you need them.

View all additional Salt packages

Package	Purpose
@salt-ds/ag-grid-theme	Salt styling for AG Grid data grids.
@salt-ds/countries	Country flag symbols used by Country Symbol.
@salt-ds/date-adapters	Adapters that let date components work with Luxon, Moment, date-fns or Day.js.
@salt-ds/date-components	Date input, date picker and calendar components.
@salt-ds/embla-carousel	Carousel component built on Embla.
@salt-ds/highcharts-theme	Theme and useChart hook for Highcharts, used by Chart.
@salt-ds/react-resizable-panels-theme	Salt styling for react-resizable-panels, used by Splitter.

Salt requires the Open Sans and PT Mono web fonts. You can integrate them into your application using one of the following methods.

If you’re planning to use the JPM Brand theme (recommended in step 3), you’ll also need the Amplitude web font—see Setting up the JPM Brand theme in Themes for where to obtain the font files and the @font-face declarations.

With Fontsource, you can include the web font files into your build and self-host them. This is the recommended approach for enterprise applications because it avoids third-party requests at runtime.

First, install the relevant npm packages:

Next, import the CSS for the weights and styles that Salt requires. In a typical React project setup, the best place to put these imports is in your src/index.tsx file:

View the Fontsource import list

Learn more about Fontsource.

To load the fonts directly from Google Fonts, add the following into your application’s index.html file:

Refer to the Google Fonts page for more information.

If you prefer not to use Fontsource or Google Fonts, you can use any other method to incorporate the web fonts. Make sure the CSS @font-face declarations associate the correct font-family, font-weight and font-style with the corresponding web fonts.

View the web fonts, widths and styles

Font family	Weight	Style
Open Sans	300	normal
Open Sans	300	italic
Open Sans	400 / normal	normal
Open Sans	400 / normal	italic
Open Sans	500	normal
Open Sans	500	italic
Open Sans	600	normal
Open Sans	600	italic
Open Sans	700 / bold	normal
Open Sans	700 / bold	italic
Open Sans	800	normal
Open Sans	800	italic
PT Mono	400 / normal	normal

The @salt-ds/theme package ships two themes:

• JPM Brand—recommended for all new projects. Salt’s long-term visual style, aligned with the J.P. Morgan brand.
• Legacy (UITK)—for applications migrating from UITK that need to preserve the existing visual style.

Additional themes, such as Chase, are distributed as separate packages. See Themes for a full comparison.

Apply themes using the provider components (<SaltProvider> or <SaltProviderNext>), which also provide context for other settings such as mode and density.

Set up the Amplitude web font first (see step 2). In a typical React project, add the provider to src/index.tsx as follows:

Using the Legacy theme

Use this provider when migrating an existing UITK application that needs to preserve its visual style.

Both <SaltProvider> and <SaltProviderNext> accept mode and density props that control the overall look and feel of your application:

• mode—"light" (default) or "dark". See Modes.
• density—"high", "medium" (default), "low", "touch" or "mobile". See Density.

Add these props to the provider, alongside any theme props from earlier:

Refer to the SaltProvider docs for the full API.

Salt components style themselves through component classes and never touch bare HTML tags. Typography, color, and focus styles are applied by the .salt-theme class from global.css and only apply inside that scope. Anything you render outside a Salt component—plain <h1>, <p>, <ul>, <button>, <a>—still picks up the browser's default user-agent styles, which vary between browsers and often conflict with Salt layouts (oversized headings, default list bullets/indentation, bright-blue links, browser button chrome, etc.).

To avoid this, @salt-ds/theme ships an opt-in baseline reset. Import it once at the root of your app, after the theme CSS:

The reset is deliberately minimal. It:

• Applies box-sizing: border-box globally.
• Zeroes browser default margin and padding on common block elements (h1–h6, p, ul, ol, dl, dd, blockquote, pre, figure, fieldset, hr).
• Makes headings inherit font-size and font-weight so bare <h1> doesn't break layouts.
• Sets sensible defaults for media (img, svg, …), form controls, bare <button>, <fieldset>, <table>, and <a>.

It deliberately does not set body background/color, restyle lists, or override motion preferences—those are app-level decisions.

The reset is safe to use alongside Salt: every Salt component styles itself via a class selector, which wins by specificity over the reset's bare tag selectors. Non-Salt markup in your app will have its browser defaults normalized.

To use a Salt UI component, import it from the @salt-ds/core package and reference it in your JSX.

For example:

Browse the available components for their full APIs.

The @salt-ds/lab package contains new components that are in the early stages of development. Once they’re stable, they’re promoted to the core package.

Because the package is unstable and may introduce major breaking changes, lab components aren’t recommended for production. Early adopters are welcome to experiment with them.

To try them out, install the package: