---
title: Show a survey
description: Request a particular survey with show(), including identifiers, return values, force and eligibility limits.
package: "@userreason/js"
version: "0.5.4"
url: https://docs.userreason.com/sdk/show/
updated: 2026-10-16
---

# Show a survey

Use `show()` for a deliberate request to display one survey, such as a feedback button. For a business action that should be recorded, use [event()](https://docs.userreason.com/sdk/events/index.md).

## Signature

```ts
UserReason.show(surveyId: string, options?: ShowOptions): Promise<boolean>
```

| Parameter | Meaning |
| - | - |
| `surveyId` | The public survey ID (campaign ID), or its underlying survey ID. Prefer the survey ID returned by the dashboard or CLI. |
| `options.force` | Defaults to `false`. Asks the API even for a survey it said is held for this visitor. The API still decides. |

## Example

This example adds a feedback button. Replace both placeholders with IDs from the same site. Configure the published survey with a **page-load trigger**. Disabling automatic triggers keeps it from opening before the button is clicked.

```ts title="src/feedback.ts"
import UserReason from '@userreason/js';

UserReason.init({ siteId: 'YOUR_SITE_ID', automaticTriggers: false });
await UserReason.ready();

const button = document.createElement('button');
button.type = 'button';
button.textContent = 'Give feedback';
button.addEventListener('click', async () => {
  try {
    const displayed = await UserReason.show('YOUR_PROMPT_ID');
    if (!displayed) console.info('No feedback survey is available right now.');
  } catch (error) {
    console.error('Could not display feedback', error);
  }
});
document.body.append(button);
```

Run in the browser after the document body exists. Initialize once for your app; do not add a second initialization with different options to an existing integration.

## Rules still apply

Managed `show()` evaluates a **page-load opportunity** for the selected survey. The survey must have a matching page-load trigger. An event-only survey remains ineligible; `show()` cannot fabricate an application event.

The survey must be published, supported by the installed SDK, in the visitor's sampled cohort and eligible for its audience and server frequency rules. A permanent decline also prevents display. Only one UserReason widget can be open at a time.

`force: true` only skips the SDK's own shortcut for surveys the API said are held. It does **not** bypass sampling, audience, server frequency, permanent decline or trigger matching. Use a development site and a fresh visitor when testing.

## Return value and errors

`true` means the widget was mounted; it does not mean the visitor saw every question or submitted a response. Use the [shown and submitted notifications](https://docs.userreason.com/sdk/notifications/index.md) for those lifecycle moments.

`false` means it could not display, including failed eligibility, a missing document body, another active widget, or execution outside a browser. Calling before initialization in the browser throws; an unknown published survey ID rejects. Loading and network failures can also reject, so catch the promise.