Events and errors

The DOM events the element fires and the error codes onestar:error carries.

The <onestar-feedback> element fires DOM events as the form loads, opens, is answered and closes, and onestar:error when something stops it. Each event's detail names the form and never anything about the person answering.

Listening#

Events bubble and cross the shadow root, so you can listen on the element or on window:

const form = document.querySelector("onestar-feedback");
form.addEventListener("onestar:submit", (e) => {
  if (e.detail.final) console.log("Finished", e.detail.form);
});

window.addEventListener("onestar:error", (e) => {
  console.warn(e.detail.code, e.detail.message);
});

Listen before the form loads (anywhere before or right after the element), so you do not miss onestar:ready or an early onestar:error. For React, Vue and Svelte, see Frameworks.

Events#

Notes on a few of them:

• block on onestar:answer is the question id, the same id the form builder shows.
• onestar:submit from onestar.submit() (your own UI) is fired on window only, since there is no element.
• onestar:replied can fire twice for one form: once from the unread check on an overlay's button, and once when the form loads and shows "The makers replied". unread may be 0 on the second when the replies were already read.
• onestar:reply fires from the conversation view inside a form. mode="thread" and <onestar-inbox> do not fire it.
• origin is present only on onestar:error with origin_refused.
• message is one plain sentence you may show or log.

Error codes#

onestar:error carries one of these codes. Codes OneStar adds later pass through as they are, so treat an unknown code like server.

These are not errors and fire nothing, because the form shows them to the person itself:

• An answer the person can fix, such as a missing required answer or a badly typed email. The form shows the message beside the question.
• A second answer to a form that allows one answer per person. The form shows "You already answered this. Thanks."

onestar.submit() rejects with the same codes, plus closed, invalid_answer and already_answered; see Your own UI.

Console messages#

Some problems only you can fix, so the widget also writes one line to the browser console:

For a form for signed in users with no token, the onestar:error message says: "This form is for signed in users and no user token is set. Call onestar.identify(token) or set user-token."

TypeScript#

To type the events on elements and on window, add this to a .d.ts file:

type OneStarErrorCode =
  | "origin_refused" | "form_closed" | "invalid_form" | "network" | "load_failed" | "identity_required"
  | "stale_form" | "version_changed" | "too_fast" | "not_found" | "rate_limited" | "server"
  | (string & {});

interface OneStarEventMap {
  "onestar:ready": CustomEvent<{ form: string }>;
  "onestar:open": CustomEvent<{ form: string }>;
  "onestar:answer": CustomEvent<{ form: string; block: string }>;
  "onestar:submit": CustomEvent<{ form: string; final: boolean }>;
  "onestar:close": CustomEvent<{ form: string }>;
  "onestar:replied": CustomEvent<{ form: string; unread: number }>;
  "onestar:reply": CustomEvent<{ form: string }>;
  "onestar:error": CustomEvent<{ form: string; code: OneStarErrorCode; message: string; origin?: string }>;
}

declare global {
  interface HTMLElementEventMap extends OneStarEventMap {}
  interface WindowEventMap extends OneStarEventMap {}
  interface HTMLElementTagNameMap {
    "onestar-feedback": HTMLElement;
    "onestar-inbox": HTMLElement;
  }
}

export {};

With it, document.querySelector("onestar-feedback") returns an HTMLElement, and e.detail.final in an onestar:submit listener on it or on window is typed.