Salsa.js is our browser-side JavaScript library that let's you easily embed Salsa’s pre-built UI elements in your payroll application. In this guide, you'll learn to set up Salsa.js, and create and mount an element.

Load and initialize Salsa.js

The first step is to to load Salsa.js into your application:

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

📘

Asynchronous loading

Use the async or defer attributes to load the script asynchronously.

Next, create an instance of the Salsa.js using your Client Key and specifying the environment:

const salsa = window.Salsa('my-public-client-key', {env: 'sandbox'});

Insert a UI element

Create an element instance in your desired view, and specify its name.

const demoElement = salsa.elements.create('demo');

📘

Authorization

Many elements that you will use in a production application will require a user token for authorization.

Next, create an empty div that will act as a container for your element.

<div id='salsa-container' /> 

Now mount the element inside of the div you just created.

salsa.elements.mount(demoElement, '#salsa-container');

When your view loads, you should see the demo element embedded in your application.

Handle load failures

Occasionally an element may fail to load. Salsa.js renders nothing in the container when this happens, so without a listener your users see an empty space.

Listen for the error event and show your own fallback. Register the handler before you mount, so it is in place if the first load fails.

demoElement.on('error', (error) => {
  showYourFallbackUi(error);
});

For what the event covers and when it fires, see the error event in the Salsa.js reference.

Cleanup

When unmounting a view that contains a Salsa UI element, make sure you call destroy to clean up any open items.

salsa.elements.destroy(demoElement);

Embed in a mobile app

To show elements inside a native mobile app, load your page in a WebView. Downloads need some extra setup in the WebView. See Handle downloads in mobile apps.