> For the complete documentation index, see [llms.txt](https://docs.zigpoll.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zigpoll.com/javascript-api.md).

# Javascript API

The `window.Zigpoll` object also carries three data members documented on their own pages: [`window.Zigpoll.user`](/embed/participant-metadata.md) (participant identity and metadata), [`window.Zigpoll.metadata`](/embed/poll-metadata.md) (survey metadata), and [`window.Zigpoll.templateVariables`](/questions/template-variables.md) (dynamic question copy).

To gate Zigpoll on a visitor's cookie consent, see [Cookie Consent](/cookie-consent.md) for `window.Zigpoll.consent()` and `window.Zigpoll.requireConsent`.

#### Single Page **Web** Apps

If you have a single page website you can still use Zigpoll. All you need to do is run the following code immediately **after** you change a page within your app.

```javascript
window.Zigpoll.refresh();
```

#### Programmatically Toggle The Poll

If you want to toggle your Zigpoll programmatically (like when a user clicks a button) use the following function.

```javascript
window.Zigpoll.toggle();
```

This will toggle your Zigpoll open and closed.

Alternatively you can use:

```
window.Zigpoll.open();
window.Zigpoll.close();
```

To open and close the Zigpoll respectively.

#### Trigger Event Once Zigpoll Is Loaded

To trigger some behavior once the Zigpoll has loaded, use the onload parameter of the Zigpoll object. For example:

```
window.Zigpoll.onload = function () { console.log('Zigpoll loaded') }
```

This will run once immediately after the Zigpoll has been loaded on your page.

#### Trigger Event When A Question Is Answered

To react the moment a respondent answers a question — before they finish the survey — set the `onAnswer` parameter of the Zigpoll object:

```
window.Zigpoll.onAnswer = function (answer, responses) { console.log(answer.slide.title, answer.value) }
```

`onAnswer` is called once for each answer, right after Zigpoll has saved it, for every question type. It receives two arguments:

* `answer` — the answer that was just given. It has the same shape as an entry in `onClose` / `onComplete`: `slide` (the question, including its `handle`, `title`, and `type`) and `response` (the submitted answer; multi-select questions also include a `responses` array). It also carries `value`, the answer as a single display string — the text of the chosen option, the typed text, the rating, or the selected options joined with commas.
* `responses` — every answer submitted so far in this survey, in question order, in the same shape.

Match on the question's `handle` (set it under the question's settings so it does not change when you edit the title) to act on one specific question:

```
window.Zigpoll.onAnswer = function (answer) {
  if (answer.slide.handle === 'plan-interest') {
    window.dataLayer.push({ event: 'zigpoll_plan_interest', value: answer.value });
  }
}
```

`onAnswer` fires again if a respondent edits an answer (when editing is allowed), so treat the latest call for a given `handle` as the current answer. Errors thrown inside your function are logged and never stop the survey from advancing.

#### Trigger Event When Zigpoll Is Completed

To run some behavior once a respondent has answered every required question, set the `onComplete` parameter of the Zigpoll object:

```
window.Zigpoll.onComplete = function (responses) { console.log('Zigpoll completed', responses) }
```

`onComplete` fires once per survey, with the respondent's submitted answers in the same shape as `onClose` below. Use `onClose` instead if you also want to hear from respondents who leave partway through.

#### Trigger Event When Zigpoll Is Closed

To run some behavior when a respondent closes the Zigpoll — for example after they finish a survey — set the `onClose` parameter of the Zigpoll object:

```
window.Zigpoll.onClose = function (responses) { console.log('Zigpoll closed', responses) }
```

`onClose` is called with the respondent's submitted answers: an array with one entry per answered question. Each entry contains the `slide` (the question) and the `response` (the submitted answer); multi-select questions also include a `responses` array.

```
window.Zigpoll.onClose = function (responses) {
  responses.forEach(function ({ slide, response }) {
    console.log(slide.title, response);
  });
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zigpoll.com/javascript-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.