📘

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:

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:

options.style properties:

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