> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Web Elements
> Embed Tilta's onboarding and payment flows directly in your app using Widgets and Modals – fast to implement, easy to brand, no back-end UI work needed.
Tilta Web Elements let you embed fully functional onboarding and payment flows directly inside your platform's UI. Instead of redirecting users away from your application, you render Tilta's flows as a **Widget** (an inline component within your page layout) or a **Modal** (a full-screen overlay triggered by a button or event). Both options use the same SDK and short-lived JWT tokens, so you get a branded experience without building the underlying financial flows yourself.
## Prerequisites
Before installing the SDK, confirm your environment meets the following requirements:
* **Node.js** v12.x or later
* **npm** 6.x or later, or **yarn** 1.22.x or later
* Your application must be served over **HTTPS** (Content Security Policy headers are enforced). Localhost is also supported for development.
* A Tilta account with sandbox access – contact [support@tilta.io](mailto:support@tilta.io) if you do not have credentials yet.
## Installation
Choose the installation method that fits your stack:
```bash theme={null}
npm install @tilta/embed
```
```bash theme={null}
yarn add @tilta/embed
```
Add the following `
```
If you plan to use the Modal component, include Tilta's CSS file so the overlay renders correctly:
```html theme={null}
```
Place this inside the `` tag of your HTML, or import it at the top of your root stylesheet.
When using the npm or yarn package, import the functions you need at the top of your component or script file:
```js theme={null}
import { createWidget, createModal } from '@tilta/embed';
```
Web Elements are authenticated with a short-lived JWT. Request a token from the Tilta API on your server before rendering any element, and pass it to the client. Never generate or store tokens in client-side code.
```bash theme={null}
curl --request POST \
--url https://api.tilta-sandbox.io/v1/tokens \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"buyer_external_id": "buyer_001"}'
```
The response contains a `token` string – pass this to `createWidget` or `createModal` in the next step.
## Rendering a widget
A Widget renders Tilta's flow inline within your page. Add a container `div` to your markup and then call `createWidget` with the session token.
```jsx React theme={null}
import { useEffect } from 'react';
import { createWidget } from '@tilta/embed';
export function TiltaWidget({ token }) {
useEffect(() => {
createWidget(token);
}, [token]);
return ;
}
```
```js Vanilla JS theme={null}
import { createWidget } from '@tilta/embed';
document.addEventListener('DOMContentLoaded', function () {
createWidget('your_token_here');
});
```
Make sure your markup includes the target container element before `createWidget` is called:
```html theme={null}
```
In React, wrapping the `createWidget` call inside a `useEffect` with the token as a dependency ensures the Widget re-initialises correctly if the token is refreshed.
## Rendering a modal
A Modal overlays the current page when triggered. `createModal` returns a `toggle` function that you attach to any button or event handler.
```jsx React theme={null}
import { createModal } from '@tilta/embed';
export function TiltaModalButton({ token }) {
const { toggle } = createModal(token);
return (
);
}
```
```js Vanilla JS theme={null}
import { createModal } from '@tilta/embed';
const { toggle } = createModal('your_token_here');
document.getElementById('activateModal').onclick = toggle;
```
Make sure the Modal CSS is loaded (see the installation steps above) before `toggle` is called for the first time. Without the stylesheet the overlay will not render correctly.
## Token lifecycle
Tilta session tokens are short-lived JWTs. Keep the following in mind:
* Tokens expire after a short period – generate a fresh token for each user session.
* Always generate tokens server-side using your API key, then pass them to the browser.
* If a token expires while the Widget or Modal is open, the user will see an authentication error. Handle this by catching the error event from the SDK and requesting a new token.
## Troubleshooting
Check that the container element (``) exists in the DOM before `createWidget` is called. If you are using a framework like React, ensure the component has mounted before calling the SDK – use `useEffect` rather than calling `createWidget` at the module level.
Your server's CSP headers must allow scripts and frames from Tilta's domains. Add the following to your `Content-Security-Policy` header:
```
script-src 'self' https://embed.tilta-sandbox.io https://embed.tilta.io;
frame-src 'self' https://embed.tilta-sandbox.io https://embed.tilta.io;
```
For local development, also permit `localhost` in the relevant directives.
Verify that the `` tag for `modal.css` is included in your HTML `` before the Widget or Modal is initialised. If you are importing CSS via a bundler, make sure the import is not being tree-shaken or conditionally excluded.
If you installed the SDK via npm or yarn, confirm the import path is correct:
```js theme={null}
import { createWidget, createModal } from '@tilta/embed';
```
If you are using the CDN script tag, the functions are available on the global `Tilta` object. Check the browser console to confirm the script loaded without errors.
Tokens must be generated server-side for the correct buyer and environment (sandbox vs. production). Confirm that:
* You are using the right base URL for your environment.
* The `buyer_external_id` in the token request matches a registered buyer.
* The token is being passed to the SDK immediately after generation and has not expired in transit.