` | Floating chat bubble anchored to the corner. |
| **Fullpage** | `data-perspective-fullpage` | `
` | Full-viewport interview experience. |
Button-based types (Popup, Slider) require a `
` element. The user clicks it to open the interview.
### Examples
**Inline widget:**
```html
```
**Popup triggered by a button:**
```html
Share your feedback
```
**Slider triggered by a button:**
```html
Open interview
```
**Floating chat bubble:**
```html
```
## URL Parameters
Pass parameters via the `data-perspective-params` attribute as comma-separated `key=value` pairs:
```html
```
### Built-In Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `email` | string | Pre-fill participant email. Also stored as an Input Param. |
| `name` | string | Pre-fill participant name. Also stored as an Input Param. |
| `returnUrl` | URL | Redirect URL after interview completion. |
| `voice` | `"0"` | Set to `"0"` to disable voice mode (text-only). |
| `scroll` | `"0"` | Set to `"0"` to disable scroll mode. |
| `hideProgress` | `"true"` | Hide the progress bar. |
| `hideGreeting` | `"true"` | Hide the welcome greeting at the start. |
| `hideBranding` | `"true"` | Hide the branding header (logo and company name). |
| `enableFullScreen` | `"true"` / `"false"` | Show or hide the fullscreen button. Defaults to `"true"`. |
Any unrecognized parameters are treated as custom key-value pairs. They are passed through to webhooks and data exports, making them useful for attribution and tracking (e.g., `campaign=summer2024`).
Custom parameters have no application-specific count or key-name length cap. Total URL and request size limits still apply. Values in agent prompts and MCP batch transcripts are sanitized and truncated to 50 characters. Stored values, exports, and webhooks retain the decoded URL values. See [Custom parameter limits](/docs/guide/design/url-parameters#custom-parameter-limits) for details.
The SDK also forwards search parameters from the parent page URL into the embed iframe, except for SDK-owned parameters such as `embed`, `embed_type`, `theme`, and `brand.*` color keys. Parameters passed explicitly through `data-perspective-params` or the JavaScript `params` option override forwarded parent-page values. Custom context values become Input Params, visible in the **Input** tab of conversation results. For details, see [Track Input Params](/docs/guide/collect/track-participant-context).
## Theming
### Color Mode
Force a color mode with `data-perspective-theme`:
```html
```
Accepted values: `dark`, `light`, `system` (default, follows OS preference).
### Brand Colors
Override brand colors with `data-perspective-brand` (light mode) and `data-perspective-brand-dark` (dark mode):
```html
```
Available color tokens:
| Token | Description |
|-------|-------------|
| `primary` | Primary accent color — applied to buttons, the progress bar, links, the voice mic, and focus rings. |
| `bg` | Background behind the interview card. Only visible when no background scene is set; otherwise the scene covers it. |
Other tokens (such as `secondary` and `text`) are not applied and are ignored.
## Widget Appearance
The inline **Widget** renders as a centered, framed card by default — bordered, rounded, with a soft shadow and a themed background — so it looks finished without any custom CSS. The widget adapts to how you size its container:
- **Drop it in without sizing** and it renders as a centered card (default max width `480px`, min height `640px`).
- **Size the container yourself** — an explicit height, `height: 100%`, or a flex/grid cell — and it fills that space edge to edge with no framing.
Override the auto-detection and individual card styles with `data-perspective-frame`, a comma-separated list of `key=value` pairs:
```html
```
| Key | Description | Default |
|-----|-------------|---------|
| `layout` | `card` to always frame, `fill` to always fill edge to edge. Omit to auto-detect from the container's sizing. | auto |
| `maxWidth` | Card max width, e.g. `720px` or `none`. Card layout only. | `480px` |
| `minHeight` | Minimum height, e.g. `720px`. Applies in both layouts. | `640px` card / `500px` fill |
| `radius` | Card `border-radius`, e.g. `4px`. | theme radius |
| `border` | Card `border` shorthand, e.g. `1px solid #ddd` or `none`. | themed `1px` border |
| `shadow` | Card `box-shadow`, e.g. `none`. | soft shadow |
| `bg` | Card `background`, e.g. `#ffffff`. | theme background |
Every key except `layout` maps to a `--perspective-widget-*` CSS custom property (`--perspective-widget-max-width`, `--perspective-widget-min-height`, `--perspective-widget-radius`, `--perspective-widget-border`, `--perspective-widget-shadow`, `--perspective-widget-bg`), so you can also set these from your own stylesheet. `layout` has no CSS variable — it only controls the card-vs-fill decision. Inline `data-perspective-frame` values take precedence over stylesheet variables, which take precedence over the built-in defaults.
With the JavaScript API or NPM SDK, pass these as a `frame` object. The field names match the attribute keys above, except the background field is `background` (the shorter `bg` is only an alias accepted inside the `data-perspective-frame` string):
```javascript
Perspective.createWidget(container, {
researchId: "RESEARCH_ID",
frame: { layout: "card", maxWidth: "720px", shadow: "none", background: "#ffffff" },
});
```
In React, pass the `frame` prop to `` with the same fields:
```tsx
Ask a question
```
For the JavaScript API:
```javascript
Perspective.openSlider({
researchId: "RESEARCH_ID",
sliderMode: "push",
});
```
For React:
```tsx
const { open } = useSlider({
researchId: "RESEARCH_ID",
sliderMode: "push",
});
```
## Auto-Open (Popup Only)
Trigger a popup automatically without a user click:
```html
```
**Auto-open triggers:**
- `timeout:N` -- Opens the popup after `N` milliseconds.
- `exit-intent` -- Opens when the user moves their cursor toward the browser chrome (desktop only).
**Show-once options:**
- `session` -- Show once per browser session.
- `visitor` -- Show once per visitor (persisted in localStorage).
- `false` -- Show every time.
## Welcome Teaser (Float Only)
Float embeds can show a **welcome teaser** — a message bubble that appears above the launcher button after a short delay, along with a chime sound and a notification dot. The teaser text comes from the interview's `welcomeMessage`.
Control the teaser with a `teaser` object through the JavaScript API or NPM SDK:
```javascript
Perspective.createFloatBubble({
researchId: "RESEARCH_ID",
welcomeMessage: "Have a question? I'm here to help.",
teaser: {
enabled: true, // false disables the whole welcome sequence (bubble, chime, dot)
delay: 5000, // ms after mount before the teaser appears (default: 3000)
sound: false, // mute the chime (default: true)
},
});
```
- `enabled: false` turns off the teaser bubble, the chime sound, and the notification dot entirely.
- `delay` sets when the teaser bubble appears, in milliseconds.
- `sound: false` mutes the chime while keeping the teaser bubble.
For script embeds, set the teaser data attributes on the trigger element:
```html
```
In React, pass the `teaser` prop to `` (or the `useFloatBubble` hook):
```tsx
("#perspective-widget");
const widget = createWidget(container, {
researchId: "RESEARCH_ID",
params: { source: "app", user_id: "123" },
});
const popup = openPopup({ researchId: "RESEARCH_ID" });
const slider = openSlider({ researchId: "RESEARCH_ID" });
const float = createFloatBubble({ researchId: "RESEARCH_ID" });
const fullpage = createFullpage({ researchId: "RESEARCH_ID" });
const config = await fetchEmbedConfig("RESEARCH_ID");
widget.unmount();
popup.destroy();
float.open();
float.close();
```
`createWidget` accepts an `HTMLElement | null`. If you want selector-based mounting, use the browser global `Perspective.mount("#selector", config)` or resolve the element before calling the NPM function.
## React SDK
For React and Next.js apps, use `@perspective-ai/sdk-react` instead of the script tag. It provides typed components and hooks with full lifecycle control.
### Installation
```bash
npm install @perspective-ai/sdk-react
```
### Widget (Inline Embed)
Renders the interview directly inside a container element:
```tsx
import { Widget } from "@perspective-ai/sdk-react";
function FeedbackWidget() {
return (
console.log("Loaded")}
onSubmit={() => console.log("Completed")}
/>
);
}
```
The `Widget` component accepts all standard `div` props (`className`, `style`, etc.) for sizing and layout, plus a `frame` prop to control its card appearance — see [Widget Appearance](#widget-appearance).
### Popup
Use the `usePopup` hook for modal overlays:
```tsx
import { usePopup } from "@perspective-ai/sdk-react";
function FeedbackButton() {
const { open, isOpen } = usePopup({
researchId: "RESEARCH_ID",
onSubmit: () => console.log("Completed"),
});
return Give Feedback ;
}
```
### Slider
Use the `useSlider` hook for a side panel that slides in from the edge:
```tsx
import { useSlider } from "@perspective-ai/sdk-react";
function SliderTrigger() {
const { open } = useSlider({ researchId: "RESEARCH_ID" });
return Open Survey ;
}
```
### Float Bubble
A floating chat bubble anchored to the corner of the page:
```tsx
import { FloatBubble } from "@perspective-ai/sdk-react";
function App() {
return
` where you want it. |
| `popup` | A button that opens a modal. | Add the button to your page yourself, for example `Share feedback `. |
| `slider` | A button that opens a side panel. | Add the button to your page yourself, for example `Share feedback `. |
If the page already has a `data-perspective-*` element with the same ID and type, the tag uses it instead of adding another one.
Then choose when the tag runs:
1. Add a **DOM Ready** trigger that fires on all pages, or only on the pages that should show the conversation. Don't use **All Pages** or another **Page View** trigger. Those fire before the page's HTML has loaded, so the tag can't find a `data-perspective-*` element you placed yourself, and the conversation appears in the wrong place.
2. If your site changes pages without a full reload, also add a **History Change** trigger with the same page filter, so the tag runs again on each new page where the conversation belongs.
3. Use **Preview** to check the conversation appears where you expect, then **Publish**.
The tag can run before the Perspective script finishes downloading. Its calls wait and run once the script is ready. Running the tag again, for example on a History Change, doesn't show the conversation twice. If your app replaced the page content, the conversation moves to the new page, and a float that was open stays open.
On a site that changes pages without a full reload, the tag copied from the dashboard removes the conversation when the visitor moves to a page where it doesn't run again. That's why the **History Change** trigger is needed: without it, the conversation disappears after the first in-app navigation. The minimal tag doesn't do this, so a float or full-page conversation already on screen stays when the visitor moves to a page your triggers exclude. To remove it there, add a second Custom HTML tag that fires on **History Change** for those pages:
```html
```
When the visitor returns to an included page, the first tag shows the conversation again.
### Track Conversations in Google Analytics
Each embed pushes these events to the `dataLayer`:
| Event | When it fires |
|-------|---------------|
| `perspective_widget_open` | A widget or full-page conversation appears on the page, or a visitor opens a popup, slider, or float. |
| `perspective_widget_ready` | The conversation has loaded and the visitor can use it. |
| `perspective_conversation_started` | The participant sent their first message. A conversation resumed after a reload doesn't send it again. |
| `perspective_conversation_completed` | The participant finished the conversation. This is the same moment `onSubmit` fires. |
| `perspective_widget_close` | The visitor closed the conversation, or your page removed it. Fires once per open. |
Each event also carries `perspective_research_id` and `perspective_embed_type` (`widget`, `popup`, `slider`, `float`, or `fullpage`). In Tag Manager, read them with a Data Layer Variable to break results down by research or embed type.
```javascript
{
event: "perspective_conversation_completed",
perspective_research_id: "RESEARCH_ID",
perspective_embed_type: "float"
}
```
To count finished conversations as conversions in Google Analytics 4:
1. In Tag Manager, create a **Custom Event** trigger with the event name `perspective_conversation_completed`.
2. Create a **Google Analytics: GA4 Event** tag that fires on that trigger.
3. In Google Analytics, mark the event as a **key event**.
### Avoid Counting Conversions Twice
SDK 1.16.0 and later send these events on their own. If you already send your own Perspective events to Tag Manager, for example a `dataLayer.push` inside `onSubmit` or a Custom HTML tag that listens for `perspective:*` messages, remove that code. Otherwise each conversion is counted twice. If you want to keep your own tracking, turn the built-in events off instead.
The script at `https://getperspective.ai/v1/perspective.js` always serves the latest 1.x release, so script-tag installs already send these events.
### Turn Off the Events
| Scope | Install | How |
|-------|---------|-----|
| Whole site | Tag Manager | Add `window.Perspective("configure", { dataLayer: false });` on the line before the tag's `autoInit` call. |
| Whole site | npm or React | Call `configure({ dataLayer: false })` from `@perspective-ai/sdk` before creating embeds. |
| One embed | Script tag | Add `data-perspective-datalayer="false"` to its element. |
| One embed | npm or React | Pass `dataLayer: false` in its config, or `dataLayer={false}` to the React component or hook. |
In a React app, `configure` comes from the core package. Install it next to the React package, at the same version, so it configures the copy the components use:
```bash
npm install @perspective-ai/sdk @perspective-ai/sdk-react
```
```tsx
import { configure } from "@perspective-ai/sdk";
import { Widget } from "@perspective-ai/sdk-react";
// Every embed on the site
configure({ dataLayer: false });
// Just this one