From the dashboard
On a BYOP study, open the Invites tab and click Invite Participants. Two items give you ready-made code:
The generated code sets voice mode, dark theme, bottom-right position, full size, and the consent dialog. Change any of them with the attributes below.
Quickstart
1
Grab your code
Click Invite Participants → Copy Embed Code on the study dashboard, or call
GET /api/public/v1/studies/{study_id}/embed-code?type=widget with your Study ID.2
Install or include the widget
Run
npm install @userintuition-ai/web for React, or drop in the UMD <script> tag for plain HTML.3
Mount it
Add the generated
<userintuition-widget> element and script, or pass its values to <UserIntuitionWidget />.4
Style and scope
Set
theme, position, size, and brand colors. Use show-based-on-url and delay-interval so the widget only appears where it should.5
Test the interview
Open the page, trigger the widget, and complete a test interview. The response appears on your study dashboard.
Install
The package is published as@userintuition-ai/web.
Embedding methods
There are four ways to mount the widget. Pick the one that matches your stack.1. HTML custom element
The simplest option. Drop in the script tag and a<userintuition-widget> element anywhere in your HTML.
2. JavaScript loader
If you need to mount programmatically (for example, after a route change or user action), create the same custom element after the widget script loads.3. React component
For React apps, install the npm package and import the component.4. Web component variant
For React apps that prefer a thin wrapper around the underlying custom element, useUserIntuitionWidgetWebComponent. It is the package’s default export and the recommended React surface.
Modes
The widget supports three interview modes. Set the mode that fits your audience and the depth of feedback you want.Position and size
Control where the widget anchors and how much room it takes up on screen.Position
Size
Theme and branding
The widget ships withlight and dark presets. You can override individual colors to match your brand.
title, cta-title, cta-subtitle, start-button-text, end-button-text, and mode-specific empty-state messages (voice-empty-message, chat-empty-message, chat-placeholder, hybrid-empty-message, and others).
Consent flow
Whenconsent-required is enabled, the widget shows a consent dialog before the interview can start. The participant’s choice is stored in localStorage so they only see the dialog once per device.
Consent state is keyed by
consent-storage-key. If you change the key, the widget will treat returning participants as new and prompt them again.Smart display
You usually don’t want the widget to appear on every page or fire instantly. Use these props to scope when and where it shows.Voice and reconnect options
Voice mode has a few extra knobs for transcript display and reconnection.From the API
To fetch the same code programmatically, request its generated HTML with your Study ID:code into your page. The study must be provisioned. For a simple link instead, use type=button; that response also includes study_link.
If you build the widget markup yourself, it needs these values:
These values come pre-filled in the code from the Copy Embed Code dialog or the embed-code API. See Study lifecycle in the API reference.
Browser support
The widget runs in any modern browser that supports:- ES6+
- The Custom Elements API
- Microphone access (for voice and hybrid modes)
Next.js and React Server Components
The widget is a client-only component — it toucheswindow, localStorage, and the microphone. In Next.js 13+ with the App Router, mark the file as a client component.
Next steps
External panels
Route respondents from a panel provider you already use.
Share a study link
The simpler alternative — a hosted URL anyone can open in a browser.

