Skip to main content

​
Overview

Tesouro’s Drop-in Components is a fully embeddable UI component library built upon JavaScript’s Web Components. It facilitates the integration of diverse UI elements into your web application. You can choose to bring in individual components or use the library as a single, comprehensive component serving as an all-in-one UI solution.
Preview of Tesouro's Drop-in components library
Drop-in components responsivenessAs of this release, the Tesouro Drop-in is optimized for desktop use and may not provide the desired responsiveness on mobile and tablet views. We are actively working to enhance support for these platforms in future updates.

​
Using the Tesouro Drop-in Components library

You must provide the Tesouro Drop-in Components library as an NPM package, making it easier to load and use as a module. To use the Drop-in Components package, install the package using your preferred package manager as shown: 
npm install @tesouro/sdk-drop-in
Next, import the package into your application as shown:
JavaScript
import("@tesouro/sdk-drop-in").then(({ TesouroDropin }) => {
  // ...
});

​
The Drop-in instance

The Drop-in instance contains the UI and configuration for the Drop-in components. To create a Drop-in instance in your application: 
const dropinConfig = {
  entityId: 'ENTITY_ID',
  apiUrl: 'ENVIRONMENT_URL',
  fetchToken: async function fetchToken() {...},
};

const dropin = new TesouroDropin(dropinConfig);

dropin.create(component).mount(...);
Check all the components you can configure during the Drop-in instance creation.

​
Authentication

Drop-in credentialsThe Tesouro Drop-in library accepts only organization-user tokens as credentials within the fetchToken function. Attempting to use an app token with the library will throw an error. For more information about organization user tokens and permissions required, see Generate an organization user token and List of permissions.
If you already implemented a backend part that is capable of issuing organization user tokens, then write a function that retrieves this token. However, if you have not implemented the backend part yet but can already generate an organization and organization user token, you can also just call the POST /auth/token endpoint directly from this script, as shown below: 
async function fetchToken() {
  const request = {
    grant_type: "entity_user",
    entity_user_id: "ENTITY_USER_ID",
    client_id: "CLIENT_ID",
    client_secret: "CLIENT_SECRET",
  };

  const response = await fetch("https://api.sandbox.tesouro.com/v1/auth/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-tesouro-version": "2025-06-23",
    },
    body: JSON.stringify(request),
  });
  return await response.json();
}
Tesouro does not recommend exposing the credentials of your fetchToken function on the client side as shown earlier. For security reasons, we recommend that all Tesouro tokens are generated from your server side code.

​
Theming

You can customize the theme of the component as shown: 
const dropinConfig = {
  entityId: 'ENTITY_ID',
  apiUrl: 'ENVIRONMENT_URL',
  theme: {
    colors: {
      primary: '#562BD6',
    },
  },
  fetchToken: async function fetchToken() {...},
};

const dropin = new TesouroDropin(dropinConfig);

dropin.create(component).mount(...);

​
Localization

You can customize the locale of the component renderings as shown: 
const dropinConfig = {
  entityId: 'ENTITY_ID',
  apiUrl: 'ENVIRONMENT_URL',
  locale: {
    code: 'en-US',
    messages: {
      Sales: 'Invoicing',
      Counterparts: 'Customers',
    },
  },
  fetchToken: async function fetchToken() {...},
};

const dropin = new TesouroDropin(dropinConfig);

dropin.create(component).mount(...);

​
Next steps

You have now learned about the Tesouro Drop-in component library. For a detailed quickstart guide with detailed usage examples, see Drop-in quick start.