Skip to content

Embedded components

Being completed. The components are LexOpti’s real screens: <lexopti-client> shows a client’s page, <lexopti-case> a case’s page, <lexopti-clients> and <lexopti-cases> the lists, and <lexopti-app> LexOpti itself with its navigation; <lexopti-new-client> and <lexopti-new-case> LexOpti’s new-client and new-case forms, filled from your page.

LexOpti components are custom elements. Each one drives an iframe served by https://embed.lexopti.com: your page never sees LexOpti data or tokens, only the component’s height and a few events. To compose a component’s tag and its HTML or React code, and see it live in one of your sandboxes, use the playground.

  • Your application is a LexOpti integration: an OAuth client linked to the embed resource, and the origins of the pages that show the components registered as its embed origins (exact https://host[:port] on a public domain name, never an IP address nor a single-label intranet host; every page that frames another one included, 10 at most). Outside production, localhost and *.localhost origins are accepted too, over HTTP or HTTPS.
  • The member has linked LexOpti to your application (OAuth consent for their organization), with the lexopti:write scope that POST /v1/embed-sessions needs.
<script
type="module"
src="https://embed.lexopti.com/embed/v1.0.0.js"
integrity="sha384-2N9mNdBzYHj8ZSUxBaHxKXNPRwcwlKcJQ7PopEKhcDnoKBmAJ8RVKFcn4FXAOWTZ"
crossorigin="anonymous"
></script>

Each version of the script is a file that never changes, /embed/v1.<minor>.<patch>.js, cached for a year. Its integrity attribute holds the file’s SHA-384 hash (Subresource Integrity): the browser checks it before running the script and refuses a file that does not match. With integrity, a script from another origin needs crossorigin="anonymous"; LexOpti serves it with Access-Control-Allow-Origin: * and Cross-Origin-Resource-Policy: cross-origin.

A published version never changes a single byte: the hash you pin today stays valid as long as the version is served. LexOpti keeps an append-only record of every published version and its hash; each change to the script is checked against it, and a fix always ships as a new version, never as new bytes for an existing one.

Every version and its hash are listed at https://embed.lexopti.com/embed/v1/manifest.json, latest being the newest. To check a hash yourself: curl -s https://embed.lexopti.com/embed/v1.0.0.js | openssl dgst -sha384 -binary | openssl base64 -A.

https://embed.lexopti.com/embed/v1.js is the moving alias: always the latest v1 version, cached for five minutes, without integrity since its bytes change with each version. It brings fixes without any change on your side, as Shopify serves its App Bridge script; a pinned version only changes when you change its tag. Stripe versions Connect.js in its path (/v1.0/connect.js) without a hash; LexOpti offers both.

Whichever you load, v1 only receives compatible changes: an attribute, an event or a type of v1 is never removed nor changed.

A script that does not load leaves every component blank and silent: give your page its own message (When the script does not load).

<lexopti-client
integration="YOUR_PUBLIC_ID"
client="LEXOPTI_CLIENT_ID"
tab="classification"
></lexopti-client>
<lexopti-case
integration="YOUR_PUBLIC_ID"
case="LEXOPTI_CASE_ID"
></lexopti-case>
<lexopti-clients integration="YOUR_PUBLIC_ID"></lexopti-clients>
<lexopti-cases integration="YOUR_PUBLIC_ID"></lexopti-cases>
<lexopti-app integration="YOUR_PUBLIC_ID" path="/dashboard"></lexopti-app>
Attribute Meaning
integration Your integration’s public id (returned by POST /v1/embed-sessions as integration)
client On <lexopti-client>: the LexOpti client id (from the API, or your stored mapping)
external-ref On <lexopti-new-client> and <lexopti-client>: your own id for the client; on <lexopti-new-case> and <lexopti-case>: your own id for the case. The API’s external_ref (1 to 255 of A-Z a-z 0-9 : . _ -, an opaque technical id, never personal data). Below and below
case On <lexopti-case>: the LexOpti case id; it wins over external-ref
path On <lexopti-app>, optional: the screen it opens on (below). Without it, or with a path it does not show, the dashboard, with a warning in your page’s console
height Optional, in pixels: a fixed height; the screen then scrolls inside
display Optional: inline (default), panel or fullscreen (display modes)
locale fr or en; by default en when the lang of your page starts with en, fr otherwise
header Optional: false hides the screen’s header and stepper (breadcrumbs, title card, status, step indicators, tab bar) on <lexopti-client>, <lexopti-case>, <lexopti-new-client>, <lexopti-new-case> and the pages of <lexopti-app>, keeping the content and its actions; shown by default. <lexopti-classification> hides them by default: true shows the case’s or the client’s above the questionnaire. Applied live
tab Optional: the tab the screen opens on, one of its own (table below). An unknown tab, or one the component does not show, opens the first tab left, with a warning in your page’s console. The lists and <lexopti-app> have no tab of their own: there it is ignored, with a warning (give the tab in <lexopti-app>’s path)
features Optional: the parts to keep, comma-separated keys (table below). It can only remove parts from those your server kept in the session, never add any; an unknown key is ignored, with a warning
embed-url Only for LexOpti test environments

The component loads once integration is set, and its client or case for a client’s or a case’s page (or, on <lexopti-client> and <lexopti-case>, its external-ref).

<lexopti-new-client> shows LexOpti’s own new-client form in your page. Your page proposes what it knows of the contact with the prefill property (never an attribute: it never travels in a URL); the member checks it, completes it and creates the client. Nothing is stored in LexOpti before the member clicks the create button.

<lexopti-new-client
integration="YOUR_PUBLIC_ID"
external-ref="crm:contact:1042"
></lexopti-new-client>
<script type="module">
const form = document.querySelector("lexopti-new-client");
form.sessionProvider = sessionProvider;
form.prefill = {
type: "person",
person: {
first_name: "Camille",
last_name: "Durand",
birth_date: "1984-03-12",
nationalities: ["FR"],
},
address: {
line: "1 rue de la République",
postal_code: "69001",
city: "Lyon",
country: "FR",
},
};
form.addEventListener("lexopti-client-created", (event) => {
// event.detail: { clientId, externalRef }
});
</script>

prefill has the shape of the body of POST /v1/clients, without external_ref:

Field Values
type person or company, required: without it nothing is filled
person first_name, last_name, usage_name, birth_date (YYYY-MM-DD), birth_city, birth_country, nationalities (ISO 3166-1 alpha-2 codes, 10 at most)
company name, siren (9 digits), siret (14 digits), legal_form, registration_country, rcs
address line, postal_code, city, country (a person’s only, as in the API)

LexOpti checks every field on its own, with the API’s rule: a valid field fills the form, an invalid value, an unknown key or the other type’s section is ignored, and your page’s console says which (one warning listing them). It is plain JSON data, at most 16 KiB. Set it before the form opens, ideally with the element; it is read once, when the session opens.

With external-ref, the new client is linked to your id for your application on creation, as POST /v1/clients does with external_ref, in the same transaction: a reference already linked to another client creates nothing. If your id is already linked when the form opens, the component shows that client (“Already in LexOpti”, with its name and a link to it in LexOpti) instead of a second one. Another external-ref loads another form. Without external-ref, the client is created without a reference; link it later with PUT /v1/clients/{id}/external-ref.

<lexopti-client external-ref="…"> (without client) shows the client your id is linked to. While none is, it says so (“Not in LexOpti yet”) and, when the session keeps edit, offers “Create the client”: the same form, filled from the element’s prefill, linked to your id, after which the client’s page opens in the component. When both are set, client wins.

Once <lexopti-client> shows a client, its prefill proposes changes to that client’s identity, in the same shape (type may be left out; another type than the client’s is ignored whole). When the session keeps edit, the client’s page opens its information tab with the proposed fields filled in its real edit form and a notice saying how many: the member reviews them, then saves (the app’s own rules: an analysed client keeps its required fields, a change of a screened field under ongoing vigilance relaunches its analysis) or discards them. Nothing is written before the member saves; client.updated then tells your server. Fields already equal to the client’s are not proposals. Each ignored field is told in the console. Your server may also change an identity itself with PATCH /v1/clients/{id}.

A new client is a draft: no check runs, no credit is spent, until the member launches its analyses from its page. The component’s session is component: "new-client", with no features (the form has no part to keep: any key answers 400 invalid_features).

<lexopti-new-case> shows LexOpti’s own “New case” screen in your page, the one of the app: its natures, its clients and parties, its checks. Your page proposes the case with the prefill property (never an attribute, never in a URL); the member checks it, completes it and creates the case. Nothing is stored in LexOpti before the member clicks the create button.

<lexopti-new-case
integration="YOUR_PUBLIC_ID"
external-ref="crm:matter:7"
></lexopti-new-case>
<script type="module">
const form = document.querySelector("lexopti-new-case");
form.sessionProvider = sessionProvider;
form.prefill = {
label: "Acquisition of the PRESSE Conseil premises",
case_types: ["custom"],
custom_case_type_label: "Acquisition of business premises",
parties: [
// A client of the organization, linked to your contact: by your reference.
{ external_ref: "crm:contact:1042", role: "client" },
// The seller: its identity and your reference of it (a party's).
{
external_ref: "crm:contact:2001",
identity: {
type: "company",
company: { name: "PRESSE Conseil SAS", siren: "552100554" },
},
role: "vendeur",
},
],
};
form.addEventListener("lexopti-case-created", (event) => {
// event.detail: { caseId, externalRef }
});
</script>
Field Values
label The case’s title, 1 to 255 characters; without it, LexOpti writes it from the natures and the client
case_types The case’s natures, among those LexOpti offers the organisation’s profession; custom with custom_case_type_label (2 to 160 characters), the free nature every profession has
parties 20 at most, each with one of client_id (a LexOpti client), external_ref (your reference of a client, for your application) or identity (someone to create, in the shape of the new-client prefill, named), an optional role, and with identity an optional external_ref: the client (role client) or the party your reference already names is used, else the new one is created from the identity and linked to it

role is client by default: a client of the case, the first one its main client (an existing client by its id or your reference, or a new client created with the case from its identity). Any other role is a party of the case, created from its identity, one of the roles the organisation’s profession offers (Concepts, “Party roles”); an existing client is proposed as a client of the case only: given another role, it is dropped and reported (a party is never an existing client, since the professional’s duties to their clients would follow). LexOpti checks every field on its own: a nature or a role the profession does not offer, an unknown client id or reference, an identity without its name, an unknown key or an invalid value is ignored (a party role the profession does not offer gets the form’s own default, autre), and your page’s console says which in one warning. It is plain JSON data, at most 16 KiB, read once when the form opens.

With external-ref, the new case is linked to your id for your application in its creation’s transaction: a reference already linked to another case creates no case. If your id is already linked when the form opens, the component shows that case (“Already in LexOpti”, with a link to it in LexOpti) instead of a second one; the reference is read again before anything is created. The form creates the new clients first, then the case and its parties, as in LexOpti: should another case take your id in the instant between that reading and the creation, no case is created, the form says so, and the new clients stay in LexOpti as drafts (as when a case’s creation fails in LexOpti itself). The reference is your application’s, in the member’s organization: like <lexopti-new-client>’s, it is not bound to the session, so any page your session provider serves can name any id of yours; only a member of the organization, through your application, creates anything.

<lexopti-case external-ref="…"> (without case) shows the case your id is linked to. While none is, it says so (“Not in LexOpti yet”) and, when the session keeps edit, offers to create it: the same form, filled from the element’s prefill, linked to your id, after which the case’s page opens in the component. When both are set, case wins.

A new case is charged as it is created, as in LexOpti: its dossier opens (one credit per five people or companies, which a confirmation states before the case is created), nothing is screened until the member launches its analyses from its page, free within its places; an organisation whose subscription is inactive gets LexOpti’s own refusal (its subscription opens in LexOpti). The component’s session is component: "new-case", with no features. Your server may also create a case itself with POST /v1/cases (create a case from your record).

<lexopti-clients> and <lexopti-cases> show the organisation’s clients and cases lists as in LexOpti, with their search, filters and views. A row opens the client’s or the case’s page inside the component. In <lexopti-clients>, “New client” opens LexOpti’s new-client form inside the component while the session keeps edit (the list shows no creation entry without it); once created, the client’s page opens there and the element sends lexopti-client-created (externalRef null: the list names no reference; link the client to your record through the API, PUT /v1/clients/{id}/external-ref). A new case opens in LexOpti, in a new tab.

<lexopti-app> shows LexOpti itself in your page, with its navigation reduced to three entries: dashboard, cases and clients (no organisation selector, no organisation entry; the help and the notifications bell stay). The bell is LexOpti’s own: the member’s notifications in the linked organisation only (none about comments when the session leaves comments out), each opening its client’s or case’s page inside the component (a mention on its comment), anything else in LexOpti, in a new tab. Marking notifications read needs lexopti:read only, the member’s own read state; deleting them needs lexopti:write, and without it the bell shows no delete button. Its screens, the values of path and of navigate():

Path Screen
/dashboard The dashboard: alerts, activity, cases and clients under continuous vigilance
/clients, /cases The lists
/clients/<id>, /cases/<id> A client’s or a case’s page, with ?tab=<tab> for one of its tabs
/clients/new, /cases/new The new-client and new-case forms (with edit)

What needs LexOpti’s own window opens in LexOpti, in a new tab: the subscription and the payment, the organisation’s settings (members, connected applications), the platform’s administration, the member’s account and security, and two-factor authentication. Its “New case” entries (the dashboard, the cases list, a client’s cases) open the new-case form inside it while the session keeps edit, the client already chosen when opened from a client’s page.

<lexopti-classification> shows the risk classification questionnaire of a client (client) or a case (case, which wins) bare: its questions and answers only, no page around them, no tab rail, no score panel. With axis, one axis of a case’s questionnaire alone (axe1 the entry into the relationship, axe2 the client, axe3 the service, axe4 the operation), so your page places the axes one after another, each in its own element; a client’s questionnaire has axe2 only, the other axes show a one-line notice. axis is applied live. Saving, completing and the impact on validated cases are LexOpti’s own, exactly as in its window; the theme variables apply as on every component.

<lexopti-classification
integration="YOUR_PUBLIC_ID"
case="LEXOPTI_CASE_ID"
axis="axe1"
></lexopti-classification>
<lexopti-classification
integration="YOUR_PUBLIC_ID"
case="LEXOPTI_CASE_ID"
axis="axe2"
></lexopti-classification>

Each element needs its own session (component: classification); it has no features and shows nothing else: a link to another screen of LexOpti opens LexOpti in a new tab.

The component asks for a session when it starts and whenever its token expires (about every 10 minutes). Give it a function that asks your server for a one-time code. The component calls it with a PKCE challenge (codeChallenge, codeChallengeMethod: "S256") and its own name (component: client for <lexopti-client>, case for <lexopti-case>, clients, cases and app for the lists and <lexopti-app>, classification for <lexopti-classification>): pass them on, as is. A session opens one component only.

const element = document.querySelector("lexopti-client");
element.sessionProvider = async ({
codeChallenge,
codeChallengeMethod,
component,
}) => {
const response = await fetch("/your-server/lexopti-embed-session", {
body: JSON.stringify({ codeChallenge, codeChallengeMethod, component }),
headers: { "content-type": "application/json" },
method: "POST",
});
return { code: (await response.json()).code };
};

Your server calls POST https://app.lexopti.com/v1/embed-sessions with the member’s access token and { "origin": "<the origin of the page showing the component>", "code_challenge": "<codeChallenge>", "code_challenge_method": "S256", "component": "<component>" }, and returns the code (single use, valid 60 seconds). Never cache it. The iframe redeems it itself, with the PKCE verifier only it holds: a code read anywhere else (a log, an extension, another frame) cannot be redeemed. The resulting token stays inside the iframe.

An element keeps a provider set before the script defined it, whatever the order of your scripts. You may also give the page a single provider, which every component without its own uses, set before or after the script loads:

window.LexOpti = {
sessionProvider: async ({
codeChallenge,
codeChallengeMethod,
component,
}) => {
const response = await fetch("/your-server/lexopti-embed-session", {
body: JSON.stringify({ codeChallenge, codeChallengeMethod, component }),
headers: { "content-type": "application/json" },
method: "POST",
});
return { code: (await response.json()).code };
},
};

A session opens the one component that asked for it, like Stripe’s account sessions: a session for <lexopti-client> never serves another component, and LexOpti refuses its calls from any other. Available: client, case, clients, cases, app, new-client, new-case and classification. The lists and <lexopti-app> show only the linked organisation’s clients, cases, alerts and activity, their counters included.

Your server may also keep only some parts of the component with features, a list of stable keys in the session’s request ("features": ["monitoring", "classification", "launch-check"]); omitted, the component is whole. A key of another component answers 400 invalid_features. The component’s features attribute can then remove more, in the page and live, never add any: the parts shown are those of the session that the attribute also names. The member’s own rights still apply on top (a read-only member launches and edits nothing).

A removed part leaves no trace: its tab is not in the tab bar and never loads, its buttons and menus are not there, and the loading placeholders take the narrowed layout. A screen left with no tab shows its header and says that the page kept none of its tabs, with a link to open it in LexOpti. Whatever the page does, LexOpti refuses the calls of the parts you leave out (403 feature_disabled).

Component Tabs Actions
client, clients monitoring, cases, classification, informations, comments, activity launch-check, edit
case, cases parties, tracfin2, documents, comments, activity launch-check, edit
app The tabs of both pages: monitoring, cases, classification, informations, comments, activity, parties, tracfin2, documents launch-check, edit

A list has the keys of the page its rows open. In <lexopti-app>, both pages open from the navigation: a tab removed hides it on its page, and cases or parties no longer stop the other page from opening. There, cases, parties and informations hide their tab only: LexOpti refuses nothing for them, since the other page and the client’s file (the new-client form too) stay open from the navigation; the client’s and the case’s edits are still edit’s. activity also removes the dashboard’s activity feed.

The first tab is the one a screen opens on by default. What removing a key does:

Key Removing it
A tab Hides the tab; LexOpti refuses what that tab alone calls
cases (client) Also: the client’s cases never open inside the component, its links to them show their text only, and its case reports are refused
parties (case) Also: the case’s clients never open inside the component, and its links to them show their text only
comments, activity Hides the tab on the other screen the component opens too (a client’s case, a case’s client). Without comments, the activity shows no comment either
informations (client) Hides the client’s file; its saves are edit’s
launch-check No launch: the launch buttons are gone, and LexOpti refuses every path that would launch a check, turning continuous vigilance on (a client’s or a case party’s) and an identity change that would screen it again included (nothing is saved then)
edit No edit: the identity, its links, a case’s title, parties and assignees read only; the client’s file shows without its fields taking input. In the lists and <lexopti-app>, no creation entry either, and no new-client nor new-case form; a <lexopti-case> whose external-ref is not linked offers no creation

Save the declarations next to your code, under these names (the Vue file imports the first one):

Terminal window
curl -o src/types/lexopti-embed.d.ts https://embed.lexopti.com/embed/v1.d.ts
curl -o src/types/lexopti-embed-vue.d.ts https://embed.lexopti.com/embed/v1/vue.d.ts

lexopti-embed.d.ts types every element in document.querySelector and document.createElement (LexoptiClientElement, LexoptiCaseElement, LexoptiClientsElement, LexoptiCasesElement, LexoptiAppElement, LexoptiNewClientElement, LexoptiNewCaseElement), its attributes (LexoptiClientAttributes…, <lexopti-app>’s path as a LexoptiScreenPath), sessionProvider and its request (LexoptiSessionRequest), prefill (LexoptiClientPrefill, the body of POST /v1/clients; LexoptiCasePrefill for a new case), navigate(), refresh(), window.LexOpti, and every event in addEventListener, its detail included (LexoptiEvent<"check-completed">). Like the script, it only receives compatible changes within v1.

React 19 renders custom elements itself (React’s reference): in the browser it sets a prop as a property when the element has one, as an attribute otherwise, and listens to on<event> under the event’s exact name; on the server it renders strings and numbers as attributes and omits functions. A sessionProvider rendered before the script defined the elements would be dropped, which is why the React components exist:

Terminal window
npm install @lexopti/embed-react
import { LexoptiClient } from "@lexopti/embed-react";
import type { LexoptiSessionProvider } from "@lexopti/embed-react";
import { useState } from "react";
const sessionProvider: LexoptiSessionProvider = async (request) => {
const response = await fetch("/your-server/lexopti-embed-session", {
body: JSON.stringify(request),
headers: { "content-type": "application/json" },
method: "POST",
});
return { code: (await response.json()).code };
};
export function ClientCompliance({ clientId }: { clientId: string }) {
const [display, setDisplay] = useState<"fullscreen" | "inline" | "panel">(
"inline"
);
return (
<>
<button type="button" onClick={() => setDisplay("panel")}>
Open in a panel
</button>
<LexoptiClient
integration="YOUR_PUBLIC_ID"
client={clientId}
tab="classification"
features={["monitoring", "classification", "comments"]}
display={display}
sessionProvider={sessionProvider}
onDisplayChanged={(event) => setDisplay(event.detail.mode)}
onCheckCompleted={(event) => {
// Refresh your own view of the client here.
console.log(event.detail.outcome);
}}
/>
</>
);
}

<LexoptiClient>, <LexoptiCase>, <LexoptiClients>, <LexoptiCases>, <LexoptiApp> (its path changed live) <LexoptiNewClient> (externalRef, prefill set as the property, onClientCreated) and <LexoptiNewCase> (the same with onCaseCreated; <LexoptiClient> and <LexoptiCase> also take externalRef and prefill) render the tag (the page still loads the script, step 2): their props are the attributes, typed (tab, features as a list, height as a number, embedUrl), sessionProvider, handed to the element even before it is defined, and one on… prop per event (onReady, onCheckCompleted, onDisplayChanged…), each given the DOM event. Their ref is the element, for navigate() and refresh(). Server rendering is safe: nothing reads window while rendering, the server sends the tag and its attributes, the script upgrades it in the browser. Keep display in your state and update it from onDisplayChanged, since the member closes the panel. Without these components, write the tag yourself: <lexopti-client onlexopti-check-completed={…}>, and give the provider through window.LexOpti.

Vue 3 sets a binding as a property when the element has one, as an attribute otherwise, .prop forcing a property (Vue’s guide). Tell its compiler the tags are custom elements:

vite.config.ts
import vue from "@vitejs/plugin-vue";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag.startsWith("lexopti-"),
},
},
}),
],
});

Then pass the provider with .prop (a function is never an attribute) and listen to the events under their name:

<script setup lang="ts">
import type {
LexoptiEvent,
LexoptiSessionProvider,
} from "../types/lexopti-embed";
defineProps<{ clientId: string }>();
const sessionProvider: LexoptiSessionProvider = async (request) => {
const response = await fetch("/your-server/lexopti-embed-session", {
body: JSON.stringify(request),
headers: { "content-type": "application/json" },
method: "POST",
});
return { code: (await response.json()).code };
};
function onCheckCompleted(event: LexoptiEvent<"check-completed">) {
// Refresh your own view of the client here.
console.log(event.detail.outcome);
}
</script>
<template>
<lexopti-client
integration="YOUR_PUBLIC_ID"
:client="clientId"
tab="classification"
:session-provider.prop="sessionProvider"
@lexopti-check-completed="onCheckCompleted"
/>
</template>

With lexopti-embed-vue.d.ts in your project, vue-tsc checks the attributes (tab="nope" is an error) and infers each event’s detail. It follows Vue’s own pattern, a GlobalComponents entry per tag.

Angular refuses unknown elements unless the component declares CUSTOM_ELEMENTS_SCHEMA (Angular’s guide). Bind the attributes with [attr.…]: a plain [client] binding would set a property, which the element does not read. Bind sessionProvider as a property:

import {
Component,
CUSTOM_ELEMENTS_SCHEMA,
input,
signal,
} from "@angular/core";
import type {
LexoptiDisplayMode,
LexoptiEvent,
LexoptiSessionProvider,
} from "../types/lexopti-embed";
@Component({
selector: "app-client-compliance",
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<lexopti-client
integration="YOUR_PUBLIC_ID"
[attr.client]="clientId()"
tab="classification"
[attr.display]="display()"
[sessionProvider]="sessionProvider"
(lexopti-display-changed)="onDisplayChanged($event)"
(lexopti-check-completed)="onCheckCompleted($event)"
></lexopti-client>
`,
})
export class ClientComplianceComponent {
readonly clientId = input.required<string>();
readonly display = signal<LexoptiDisplayMode>("inline");
readonly sessionProvider: LexoptiSessionProvider = async (request) => {
const response = await fetch("/your-server/lexopti-embed-session", {
body: JSON.stringify(request),
headers: { "content-type": "application/json" },
method: "POST",
});
return { code: (await response.json()).code };
};
onDisplayChanged(event: LexoptiEvent<"display-changed">): void {
this.display.set(event.detail.mode);
}
onCheckCompleted(event: LexoptiEvent<"check-completed">): void {
// Refresh your own view of the client here.
console.log(event.detail.outcome);
}
}

With lexopti-embed.d.ts in the program, strict template checking (strictTemplates, Angular’s reference) types $event of each lexopti-… event; Angular does not check property and attribute bindings on custom elements.

Header What the components need
Content-Security-Policy script-src https://embed.lexopti.com
frame-src https://embed.lexopti.com
style-src, connect-src, img-src, font-src Nothing more: the element styles its closed shadow root with a constructed stylesheet (adoptedStyleSheets), which style-src does not govern, so no 'unsafe-inline'; it fetches nothing itself; the screen’s requests, images and fonts are its iframe’s, under LexOpti’s own policy. Your sessionProvider calls your own server
Cross-Origin-Opener-Policy Any value, same-origin included: every new tab the component opens (LexOpti, a PDF, billing) opens with noopener, and no flow needs a handle on it
Cross-Origin-Embedder-Policy Leave it unset: under require-corp or credentialless, browsers refuse a cross-origin frame that does not send that header itself, and the component’s frame does not

The components use constructed stylesheets, available in every browser since March 2023 (Chrome 73, Firefox 101, Safari 16.4).

Do not put the component in a sandboxed iframe of your own without allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads: a nested frame never gets a permission its parent lacks.

The script weighs about 8 KB compressed and only defines the elements; each component then loads its own screen in its iframe, lazily: the iframe has loading="lazy", so a component far below the fold loads when the member scrolls near it. LexOpti holds each component’s screen to a size budget, checked on every build.

When your page inserts a component late (a route of a single-page application, a drawer), warm the connections up in its <head>:

<link rel="preconnect" href="https://embed.lexopti.com" />
<link
rel="modulepreload"
href="https://embed.lexopti.com/embed/v1.0.0.js"
integrity="sha384-2N9mNdBzYHj8ZSUxBaHxKXNPRwcwlKcJQ7PopEKhcDnoKBmAJ8RVKFcn4FXAOWTZ"
crossorigin="anonymous"
/>

modulepreload fetches the script ahead, with its integrity, on the anonymous connection a module uses; preconnect, without crossorigin, opens the connection the iframe uses. Then:

  • load the script only on the pages that show a component;
  • mount a component once and keep it: each mount opens a session and loads its screen again, while navigate(), tab and display change it without reloading;
  • let the component show its own loading skeleton, in its screen’s shape: if your page shows a placeholder of its own before the script runs, hide it on lexopti-ready.

The same iframe shows in three ways; it never moves nor reloads between them, so the screen keeps its state.

display Shows Closes
inline (default) In your page, at its content’s height, or at height with the screen scrolling inside
panel A side panel on the right of the window, 720 px wide at most, over your page; below 640 px of width, fullscreen Escape, its close button, a click on the backdrop
fullscreen The whole window, over your page Escape, its close button

Set the attribute to open the panel or the fullscreen; when the member closes it, the element sets display="inline" back and dispatches lexopti-display-changed with the mode it shows (fullscreen for a panel on a narrow screen). In React, keep the mode in your state and update it from that event.

The screen’s own dialogs and drawers stay inside the area the component occupies (overlays="contained", the default): inline and sized to its content, the component clamps itself to its visible part (at least 320 px, within your page’s window or the scroll container around it) while one is open, scrolls into view, and the dialog shows there; the screen scrolls inside meanwhile, and the component takes its content’s height again when the last one closes. With overlays="fullscreen", the component goes fullscreen in your page while a dialog is open and back inline when it closes, as before. The protocol follows MCP Apps: the iframe declares the modes it supports, the element those it offers (availableDisplayModes), and a request for another mode keeps the current one.

Set these CSS variables on the element (or an ancestor, or a stylesheet rule on every lexopti-… element of your page). Each one maps onto one of LexOpti’s own design tokens; the playground composes them with a colour wheel, sliders and a fonts selector, and writes the exact rule. Colours (hex, rgb(), oklch()…) and lengths only; anything else (url(), var(), escapes, more than 64 characters) is ignored:

Variable Used for
--lexopti-accent Buttons, links, the active tab, the focus of the navigation
--lexopti-accent-foreground Text on the accent (a primary button’s label)
--lexopti-background The screen’s background and its popups
--lexopti-foreground Text
--lexopti-card Cards (and <lexopti-app>’s navigation)
--lexopti-card-foreground Text on cards
--lexopti-muted Secondary surfaces: tints, hover states, secondary buttons
--lexopti-muted-foreground Secondary text
--lexopti-border Borders
--lexopti-input The borders of fields
--lexopti-ring The focus ring
--lexopti-destructive Errors and alerts
--lexopti-warning Warnings (the vigilance’s amber)
--lexopti-success Success (the vigilance’s green)
--lexopti-radius The corner radius of every control and card (LexOpti has one radius, 10px by default)
--lexopti-font-size A multiplier of the screen’s text size, from 0.85 to 1.2 (1 by default); the whole screen scales with it, spacing included
--lexopti-font lexopti (LexOpti’s font, the default), system (your visitors’ system interface font), or a font-family stack of your own
lexopti-client {
--lexopti-accent: #15803d;
--lexopti-radius: 6px;
--lexopti-font: Georgia, "Times New Roman", serif;
}

The variables map onto LexOpti’s own design tokens: there is no free CSS and no selector. --lexopti-font takes a keyword or a stack of font names (letters, digits, spaces, commas, quotes and hyphens, at most 200 characters), applied where your visitors have those fonts and falling back to the generic family you end it with: the component never downloads a font. Any other value (a URL, a function, an escape) is ignored with a warning in your page’s console. An external font would widen the iframe’s Content Security Policy and send the member’s IP address to a third party.

The component reads the variables when it starts and whenever its style or class changes. Call element.refreshTheme() after you change them from a stylesheet of yours. LexOpti has one light theme: the screens never switch to a dark one, whatever your page’s color-scheme.

Each component tells your page what happens in it through DOM events named lexopti-<type>, without a colon: in React 19, write onlexopti-check-completed={…} on the element. They bubble and cross shadow roots; their detail is in event.detail. The list is closed and versioned (version 1): a type is never removed or changed within a version. The business events are sent once LexOpti saved the change, never on a mere click.

Event Detail When
lexopti-ready { component }, component one of client, case, clients, cases, app, new-client, new-case The component’s session is open and its screen starts: hide your own loader
lexopti-resize { height } The component sized itself to its screen (automatic layout only)
lexopti-navigate { path, title }, path one of the paths of navigate() The member opened another screen or tab of the component; keep path to come back to it with navigate(), or as <lexopti-app>’s path
lexopti-check-started { clientId } or { caseId } A check of the client or the case was launched
lexopti-check-completed { clientId } or { caseId }, and outcome: completed or failed (a control failed) The checks running for the client or the case finished
lexopti-alert-reviewed { alertId, clientId, status }, status reviewed or dismissed The member reviewed an alert
lexopti-classification-validated { clientId } or { caseId } The member validated the risk assessment
lexopti-mention-created { commentId, clientId } or { commentId, caseId } In <lexopti-app>, while its notifications bell is shown: a colleague mentioned the member in a comment of that client or case. Ids only, never the comment’s text nor its author: read the comment in LexOpti
lexopti-client-created { clientId, externalRef }, externalRef the element’s external-ref (linked to the new client), null without one The member created a client: in <lexopti-new-client>, in a <lexopti-client> whose external-ref was not linked yet, or in the form of <lexopti-clients> or <lexopti-app> (externalRef null). Read the client and its reference through the API (GET /v1/clients?external_ref=) rather than trusting the page’s event alone
lexopti-case-created { caseId, externalRef }, externalRef the element’s external-ref (linked to the new case), null without one The member created a case: in <lexopti-new-case>, in a <lexopti-case> whose external-ref was not linked yet, or in <lexopti-app>’s form. Ids only: read the case and its reference through the API (GET /v1/cases?external_ref=) rather than trusting the page’s event alone
lexopti-session-ended { reason }: access_revoked, provider_failed or expired No new session can be obtained: the member’s access ended, your sessionProvider failed, or it never answered
lexopti-display-changed { mode }: inline, panel or fullscreen The component changed its display mode: your display attribute, one of its dialogs, or the member who closed the panel
lexopti-error { type, message }, type one of session, network, not_found, forbidden, render The component could not load (it shows its own error and a retry): network when the frame served something else than the component, session when its session could not open (your sessionProvider failed, or LexOpti refused or could not be reached; too many sessions opened from one network are retried for a few seconds first, then the message says so)

Refresh your own view of the client or case on the business events (for example through GET /v1/clients/{id}).

Every screening of a client that a member starts in a screen is a check of your application, like one POST /v1/checks creates: you receive its check.completed or check.failed webhook, and GET /v1/checks lists it. These are:

  • launching the client’s analyses, or one entity’s;
  • turning continuous vigilance back on, which screens the entities edited meanwhile;
  • editing an identity, which screens it again for each client it belongs to;
  • launching a case’s analyses: one check per client it screens.

The screenings of a case’s third parties are not checks: a check names a client.

Method or attribute Effect
element.navigate(path) Shows another screen or tab of the component inside the iframe, without reloading it: /clients/<id> or /cases/<id>, with ?tab=<tab> (a tab the session keeps); for a list, its own path too (/clients, /cases); for <lexopti-app>, every path of its table. Returns a promise, rejected for any other path, before lexopti-ready, or when the component refuses it
element.refresh() Reloads the screen’s data, after your application changed something on its side. Returns a promise
locale attribute Changed after the start, applied live, without reloading the iframe
tab attribute Changed after the start, shows that tab of the element’s own screen, without reloading the iframe (once lexopti-ready fired; a change before is applied then). Removing it leaves the screen where it is
path attribute On <lexopti-app>, changed after the start, shows that screen without reloading the iframe (once lexopti-ready fired; a change before is applied then)
features attribute Changed after the start, applied live: a tab it removes gives way to the first tab left
display attribute Opens the side panel or the fullscreen, or closes it (inline), without reloading the iframe
header attribute Changed after the start, shows or hides the screen’s header and stepper live
Theme variables Set on the element’s style or class, applied live; set by a stylesheet of yours, call element.refreshTheme()

A client’s page opens its cases inside the iframe, and a case’s page its clients: both stay the same component and session. So do a list and the pages its rows open, and every screen of <lexopti-app>.

  • The component starts 760 px high (720 px for a list, 900 px for <lexopti-app> and the creation forms, <lexopti-new-client> and <lexopti-new-case>), then sizes itself to its screen’s content. With height, it keeps that height and the screen scrolls inside.
  • Until its session opens, each screen shows its own loading placeholder, with the same layout as the loaded screen, <lexopti-app>’s navigation included.
  • Your page never acts inside the screen: its clicks never reach the iframe, and only the member validates a risk level.
  • The component opens only LexOpti’s own pages in a new tab, never any other address.
  • The loading placeholder knows only the features attribute until the session opens; then the tabs the session removed leave the tab bar too. Name in the attribute what your server keeps, and nothing moves.
  • A component that shows a PDF uses LexOpti’s own viewer (browsers refuse their built-in one in a sandboxed frame) and offers to open it in a new tab.
  • A member who loses access (left the organisation, application blocked or unlinked) sees an error at their next request; a new session cannot be obtained either.
  • When the member’s session in your page ends after it opened (LexOpti refuses the exchange, or your sessionProvider refuses a new code), the screen gives way to a message with Open LexOpti and Try again, never to a sign-in form. Before any session opened (no sessionProvider, one that fails or never answers), the component shows its error: the fix is on your side.

When the browser does not run the script, because its bytes do not match the integrity of your tag, the network fails or your Content-Security-Policy blocks it, the lexopti-… tags stay undefined custom elements: no iframe, no loading placeholder, no error message, no event (not even lexopti-ready). The component’s own messages come from the script, so your page shows its own, with a link to LexOpti:

<script>
// Your message in every component, if LexOpti's script did not run.
function lexoptiUnavailable() {
for (const element of document.querySelectorAll(
"lexopti-app, lexopti-client, lexopti-case, lexopti-clients, lexopti-cases"
)) {
element.innerHTML = `<p role="alert">LexOpti is unavailable right now. <a href="https://app.lexopti.com" target="_blank" rel="noopener">Open LexOpti</a></p>`;
}
}
// A request that never ends fires no error: give up after 10 s.
const late = new Promise((resolve) => setTimeout(resolve, 10_000, null));
Promise.race([customElements.whenDefined("lexopti-client"), late]).then(
(defined) => defined || lexoptiUnavailable()
);
</script>
<script
type="module"
src="https://embed.lexopti.com/embed/v1.0.0.js"
integrity="sha384-2N9mNdBzYHj8ZSUxBaHxKXNPRwcwlKcJQ7PopEKhcDnoKBmAJ8RVKFcn4FXAOWTZ"
crossorigin="anonymous"
onerror="lexoptiUnavailable()"
></script>
  • onerror fires as soon as the browser refuses the file: hash mismatch, network error, a 404, a script your policy blocks. Define its function before the tag, in a classic script, which runs while the page is parsed.
  • Under a Content-Security-Policy without 'unsafe-inline' nor 'unsafe-hashes', the browser ignores inline handlers such as onerror="…": create the tag from your own script and attach the listener there (script.addEventListener("error", lexoptiUnavailable)), or rely on the delay alone.
  • customElements.whenDefined covers what fires no error, a request that never ends; every component is defined by the same script, so waiting for one is enough.
  • The message is the element’s own content: if the script runs after all, the element is defined, its screen takes the place and its closed shadow root shows none of that content.

Some flows need a first-party, top-level window: browsers refuse them, or restrict them, in a third-party frame (cookies, WebAuthn, payment pages). The components never show them; they open LexOpti in a new tab, through the element (only to the LexOpti app the iframe announced):

Flow In the component
Signing in, with its second factor The Open LexOpti message above
Passkeys, if the member uses them The same: WebAuthn needs a top-level window
Buying credits, subscribing, changing the plan or the payment method The quota dialog opens the organisation’s billing in LexOpti
Linking LexOpti to your application (OAuth consent) Your own page, before any component (step 1)
Accepting an invitation, the first steps of a new organisation LexOpti, outside any component
The organisation’s settings Links to LexOpti, in a new tab

The embed host does not even serve these pages: only the components’ screens, their API and the token endpoint.

  • Each iframe has a title in the component’s language (« Client LexOpti », “LexOpti client”, « Dossier LexOpti », “LexOpti case”); the panel and the fullscreen are dialogs with the same name (inline, the component is no dialog), and their close button reads « Fermer » or “Close”.
  • Opening the panel or the fullscreen moves the focus into the screen; closing it (Escape, pressed in the screen or on the close button, the close button, the backdrop) gives the focus back to the control of your page that had it, or to the screen when the member was in it.
  • While they are open, your page is inert: its keyboard focus and its scroll do not move behind them.
  • The panel slides in only when the visitor did not ask for reduced motion (prefers-reduced-motion).
  • While the screen loads, its skeleton has the screen’s shape and is announced as loading to assistive technologies; its errors are announced as alerts.