Salsa.js Web SDK

Salsa’s browser-side JavaScript library, Salsa.js.

📘

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

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" />

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.


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:

NameTypeDescription
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:

NameTypeDescription
userTokenStringA 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.
styleObjectOptions for customizing the style of the element. See the following properties table.
options.style properties:
NameTypeDescription
colorMode'light' | 'dark' | 'system'Controls what color mode will be used when rendering the element.

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.

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

NameTypeDescription
elementTypeStringThe type of Element that this event was sent for.
...--Other additional properties may be included that are specific to the Element.