JavaScript SDK reference

Everything revolves around one client created with createClient(). If you haven't set up yet, start with the JavaScript SDK guide.

createClient(options)

Create a single client and reuse it across your app. Calling createClient again with the same apiKey returns the same instance.

app.ts

import { createClient } from "@getuserfeedback/sdk";const client = createClient({ apiKey: "YOUR_API_KEY" });

Options

Option	Type	Default	Description
`apiKey`	`string`	required	Your project API key.
`colorScheme`	`"light" \| "dark" \| "system" \| { autoDetectColorScheme: string[] }`	auto-detect	Color scheme. See Dark mode.
`defaultConsent`	`"granted" \| "pending" \| "denied" \| "revoked" \| GrantScope[]`	`"granted"`	Initial consent state. See Privacy & consent.
`disableAutoLoad`	`boolean`	`false`	When `true`, call `client.load()` manually before opening surveys.
`disableTelemetry`	`boolean`	`false`	Disables anonymous performance telemetry. Does not affect user analytics.

Client methods

Identity

client.identify(userId, traits?) or client.identify(traits) — see Personalization
client.reset() — clear identity and auth state on logout

Configuration

client.configure({ colorScheme?, consent?, auth? }) — update settings at runtime
client.load() — manually start the widget when disableAutoLoad is true
client.close() — close any open flow

Flows

client.open(flowId, options?) — shorthand to open a flow
client.prefetch(flowId) — load flow resources over the network
client.prerender(flowId) — warm up the UI before opening
client.flow(flowId) — get a reusable flow handle (see below)

Observation

client.subscribeFlowState(callback, options?) — watch flow state changes
client.onOpenRequested(callback) — observe open requests before the flow renders
client.setDefaultContainerPolicy(policy) — control default container behavior

Flow handle

client.flow(flowId) returns a reusable handle for one specific flow. Use it when you want to prefetch, prerender, and open as part of one lifecycle.

feedback-button.ts

const flow = client.flow("YOUR_FLOW_ID");flow.prefetch();flow.prerender();flow.open();

Fire-and-forget vs awaiting

open(), prefetch(), prerender(), and close() return promises, but you do not have to await them for the widget to behave correctly.

The widget manages its own execution queue internally, so both of these approaches work:

flow.prefetch();flow.prerender();flow.open();

and:

await flow.prefetch();await flow.prerender();await flow.open({metadata: {tags: {journey_stage: "onboarding",},},});

Use fire-and-forget when you just want the widget to do the work. Use await when your app logic needs to know that a step finished before doing something else.

Methods

open(options?) — open the flow (options include container, metadata, and hideCloseButton)
prefetch() — load resources over the network
prerender() — warm up the UI
close() — close the flow
setContainer(element | null) — attach or detach a custom container
getFlowState() — get the current state
subscribeFlowState(callback, options?) — watch state changes

See Opening surveys from code for usage patterns, Response metadata for metadata examples, and Containers for custom container examples.