TypeScript and frameworks
The elements are standard custom elements, so any framework that renders HTML can place them. What differs between frameworks is how they type an unknown tag.
Install the declarations
Your deployment serves declarations at /embed/v1/embed.d.ts, generated from the same source
as the elements themselves.
TypeScript cannot resolve types over HTTP, so download the file into your project and let
tsconfig include it:
curl -o types/secureauth-embed.d.ts https://acp.example.com/embed/v1/embed.d.ts
The file declares the module */embed/v1/embed.js, so any import of your deployment's
/embed/v1/embed.js URL is typed. Import types from that URL too, not from the file's path: the
file is a declaration for the URL, not a module of its own.
import type { EmbedConfig } from "https://acp.example.com/embed/v1/embed.js";
It exports init, EmbedConfig, EmbedThemeTokens, the event detail types (SaErrorDetail,
SaViewChangedDetail), and SaEmbedElements, which maps each tag to its
attributes.
Do not hand-edit the downloaded file. Download it again after a deployment upgrade to pick up new elements and attributes.
What the types catch
A misspelled attribute, a value outside an enumerated set (view="nope"), and a missing
required attribute are all compile errors. That is the point of shipping them, so the
declarations carry no catch-all index signature.
Preact, Solid, Vue TSX, and React 18
The file augments the global JSX namespace, which covers these. Including it is enough.
React 19
React 19 moved JSX typing into the React.JSX namespace, so a React 19 application declares
it:
import type { DetailedHTMLProps, HTMLAttributes } from "react";
import type { SaEmbedElements } from "https://acp.example.com/embed/v1/embed.js";
type SaIntrinsics = {
[K in keyof SaEmbedElements]: SaEmbedElements[K] &
DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
};
declare module "react" {
namespace JSX {
interface IntrinsicElements extends SaIntrinsics {}
}
}
The intersection is what keeps className, event handlers, key, and ref working while the
element's own attributes stay strictly typed. Use DetailedHTMLProps rather than plain
HTMLAttributes: React sources key and ref from ClassAttributes, so the narrower form
rejects <sa-self-service key={...} />.
The same pattern is how any framework adds its own props. The declarations stay
framework-agnostic on purpose, carrying only HTML global attributes alongside each element's
contract attributes. data-* and aria-* need no declaration, because TSX does not check
hyphenated attribute names.
Loading the module
Native dynamic import() works anywhere, including inside a component:
import type { EmbedConfig } from "https://acp.example.com/embed/v1/embed.js";
const config: EmbedConfig = {
deploymentUrl: "https://acp.example.com",
tenantId: "your-tenant",
serverId: "your-workspace",
tokenProvider: () => yourAuth.getFreshToken(),
variant: "account-center",
};
const { init } = await import(/* @vite-ignore */ "https://acp.example.com/embed/v1/embed.js");
init(config);
Call init() once per page, however many elements you place. Calling it again replaces the
configuration: caches are cleared and mounted elements re-render against the new tenant or
token provider. Every call refetches everything, even with the same options, so do not call it
from a component's render. In React, call it from an effect that runs once, or at module scope.
The module needs a browser: it defines the custom elements as it loads. In a server-rendered framework such as Next.js, Nuxt, or SvelteKit, import it only on the client, for example inside an effect.
Bundlers differ on how they treat an absolute URL in import(). The comment above is Vite's
way of saying "leave this alone"; webpack honors webpackIgnore: true. Without it a bundler
may try to resolve the URL at build time.
Why there is no npm package
A loader package would inject a script tag, re-export init(), and carry types. Native
dynamic import() gives you the first two, and the served declarations give you the third, so
publishing to npm would buy nothing today while committing to a public package name and a
release cadence for a contract that has not yet been shaped by real consumers.
The emitted declarations become that package's payload when it does ship.