Skip to main content

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.

See also​