📘
Looking for a guide on how to embed UI?
This here is a reference document for the Salsa.js SDK library detailing the functionality that it provides. If you are looking for a walkthrough explaining how to embed Salsa's UI experiences inside of your own application, we recommend starting with our guide on Embedding an Element.

Including Salsa.js

There are two options for including salsa-js in your project

Load the Salsa.js script from Salsa's CDN (preferred)
Include salsa-js as an npm package

Loading Salsa.js from CDN

Load the Salsa.js script from Salsa's CDN URL by including a script tag in your web application.

You may want to specify the async or defer attributes of the script tag if you wish to load it asynchronously.

<script type="text/javascript" src="https://js.salsa.dev/v0"></script>

Once the Salsa.js script has loaded, you will be able to initialize the library via the Salsa function that is defined on the window.

Leveraging our `salsa-js` npm package

You can install our npm package into your node project

npm install @salsa-payroll/salsa-js

You can then leverage the package to instantiate a Salsa instance

import { loadSalsaJs } from "@salsa-payroll/salsa-js";

const salsa = await loadSalsaJs('ck_your-client-key');

Initializing Salsa.js

Create a `Salsa` instance

`Salsa(clientKey, options?)`

Creates an instance of the Salsa library. The returned object is your entry point to the rest of the Salsa.js SDK.
This is only needed to be done once for the lifespan of your application runtime (browser session).

Method parameters

`clientKey` _{^{REQUIRED String}}

Your application's Client Key. This is required in order to identify your application to Salsa.

Your Client Key will formatted similar to ck_f0ac...eb6d8.

`options` _{^{optional Object}}

Initialization options.

Properties:

Name	Type	Description
`env`	`'sandbox'` \| `'production'`	The environment to use, which can be either our Sandbox or Production environment. Defaults to `production` if not specified.

Salsa Elements

Salsa.js exposes a set of a powerful modular components that are designed to be easily embedded inside of your own web application to provide a seamless payroll experience. We refer to each of these components as a "Salsa Element", which you can create and interact with as described here.

Create an Element

`salsa.elements.create(elementType, options?)`

Creates an instance of an individual Salsa Element.

Method parameters

`elementType` _{^{REQUIRED String}}

The type of Element being created.

`options` _{^{optional Object}}

A set of options to create this SalsaElement instance with.

Properties:

Name	Type	Description
`userToken`	String	A User Token created with an access role that has sufficient permissions for the data that the element interacts with. This is required when using elements that require authorization, which almost all do.
`style`	Object	Options for customizing the style of the element. See the following properties table.

`options.style` properties:

Name

Type

Description

colorMode

'light' | 'dark' | 'system'

Controls what color mode will be used when rendering the element. Defaults to light if not specified.

When using system, the UI element will determine the color mode to use based on what the user's browser (and thus also operating system) specifies.

Mount an Element

`salsa.elements.mount(salsaElement, domElement)`

Attaches the SalsaElement to the DOM. The element will be inserted based on the location specified by domElement.

Method parameters

`salsaElement` _{^{REQUIRED SalsaElement}}

The SalsaElement instance to mount into the DOM.

`domElement` _{^{REQUIRED String}}

The CSS selector or DOM element where the SalsaElement will be mounted.

Destroy an Element

`salsa.elements.destroy(salsaElement)`

Removes the Element from the DOM and destroys it, additionally cleaning up any open handles and unregistering all listeners.

Method parameters

`salsaElement` _{^{REQUIRED SalsaElement}}

The SalsaElement instance to destroy.

Updating an Element's auth token

`salsaElement.replaceUserToken(newUserToken)`

Updates the user auth token without need to refresh the element. This is can be useful when you want refresh an expiring token while someone is still using the element, or to enable you to expire the access of an existing element.

For more information on how to issue user tokens see the related documentation on authorization.

Example

const salsaElement = salsa.elements.create('employer-dashboard', {
  userToken: USER_TOKEN,
  employerId: EMPLOYER_ID
});

const getSalsaUserToken = (timeToLiveInMinutes) => {
  // ...
  // This function would send a request to the Partner's own API to issue a Salsa user
  // token via a backend to backend API call, using the Partner's API Token. The 
  // Partner's backend will be responsible for determining the appropriate access role
  // and corresponding Salsa entity (employers or workers) that their current user has
  // access to.
  // ...
  return userToken;
}

const TIME_TO_LIVE_MINUTES = 5;

// Define the refresh time to be 1 minute before the expiry time (TTL)
const REFRESH_TOKEN_MILLISECONDS = (TIME_TO_LIVE_MINUTES - 1) * 60 * 1000;

// Automatically refresh the user token before the existing token expires
setInterval(async () => {
  const newUserToken = getSalsaUserToken(TIME_TO_LIVE_MINUTES);
  await salsaElement.replaceUserToken(newUserToken);
}, REFRESH_TOKEN_MILLISECONDS);

Element events

Listening to events is the mechanism through which all communication with an Element instance is provided. The events available will vary from one Element to another based on the particulars of the experience that is encapsulated, but the fundamentals in which you consume events is consistent throughout.

Listen to an event

`<SalsaElement>.on(eventName, handler)`

The on function is available on every Element and facilitates the registration of event listeners, enabling you to respond to various user interactions or custom events.. This function is designed to be familiar to developers accustomed to the native web elements' approach for for event handling and registering event listeners.

Method parameters

`eventName` _{^{REQUIRED String}}

The name of the event to listen to.

`handler` _{^{REQUIRED Function}}

handler(event) => void is the callback function that will be called whenever the event is triggered. When called, it will be passed an event object as its only parameter, of which the properties will vary based on the event being sent.

Example

// Here 'salsaElement' is a Salsa Element instance created via salsa.elements.create(), as above
salsaElement.on('complete', function(event) {
  console.log('Element complete event fired!', event);
});

Note - multiple event listeners can be attached for the same event by calling on multiple times with the same eventName.

`complete` event

The complete event is triggered when the workflow associated with the Element is completed by the user. This enables you to react to changes in your application's UI when a user is interacting with an embedded Element just as you would in your own native experiences. While this event is available for many Elements, not all Elements encapsulate a user workflow, and so it is not present for all.

Event object properties

Name	Type	Description
`elementType`	String	The type of Element that this event was sent for.
...	--	Other additional properties may be included that are specific to the Element.