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
instanceSalsa(clientKey, options?)
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
clientKey
REQUIRED StringYour 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
options
optional ObjectInitialization 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?)
salsa.elements.create(elementType, options?)
Creates an instance of an individual Salsa Element.
Method parameters
elementType
REQUIRED String
elementType
REQUIRED StringThe type of Element being created.
options
optional Object
options
optional ObjectA 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:
options.style
properties:Name | Type | Description |
---|---|---|
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)
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
salsaElement
REQUIRED SalsaElementThe SalsaElement
instance to mount into the DOM.
domElement
REQUIRED String
domElement
REQUIRED StringThe CSS selector or DOM element where the SalsaElement
will be mounted.
Destroy an Element
salsa.elements.destroy(salsaElement)
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
salsaElement
REQUIRED SalsaElementThe 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)
<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
eventName
REQUIRED StringThe name of the event to listen to.
handler
REQUIRED Function
handler
REQUIRED Functionhandler(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
complete
eventThe 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. |