Developer integration

Stand button

The stand-button web component adds a compact, page-native chat invitation that can appear for a selected live rep, AI Stand-in, or either responder and can reveal one dedicated surrounding container.

Availability: All plans
Configured in: Website HTML → <stand-button> after the Stand embed script
Category: Developer integration
Reference status: Current

Before you begin

Plan availability: All plans.

Prerequisite: An installed Stand widget and permission to add HTML to the host page.

Key boundary: Responder display filtering does not select routing or guarantee who remains assigned. Revealing an external container is a one-way page mutation.

What a Stand button does

<stand-button> is a custom element for placing a small chat call to action inside the page. Its authored contents become the visible label, while the component supplies button semantics, focus behavior, optional responder avatar, and the click that opens Stand.

The component waits for the public Stand API and subscribes to responder availability. When a selected responder matches show-when, it records the responder identity, renders the avatar if requested, and reveals either itself or one explicitly marked surrounding container.

Add it to a page

Compact chat invitation

<stand-button
  hidden
  show-when="rep"
  avatar
  message="What would you like help with during installation?"
  prompt="The visitor is reading installation instructions. Answer their question directly; ask about the website platform only if needed to give the right steps."
  analytics-id="install-help"
>
  Ask a product specialist
</stand-button>

Native hidden prevents a pre-upgrade flash. This button appears only when find or session restoration selects a live human rep.

Place the element anywhere after or before the embed script; the upgraded component retries until the API is present. The visible label comes from the default slot between the tags.

Choose the responder display rule and reveal target

Reveal surrounding copy with the button

<section hidden data-stand-reveal>
  <p>A product specialist is online.</p>
  <stand-button show-when="rep" message="What would you like to ask our team?">
    Chat with a person
  </stand-button>
</section>

Put hidden in exactly one place. Because the button is not self-hidden, it reveals its closest dedicated data-stand-reveal ancestor when the selected responder matches.

show-when evaluates the single responder selected by the current find result or restored session. It does not request a responder type, alter routing, prove that both types are available, or guarantee that the responder cannot change after chat opens.

On a match, Stand removes exactly one native hidden attribute. The component’s own hidden takes precedence; otherwise Stand uses its closest ancestor marked data-stand-reveal. It never traverses to a generic hidden ancestor or changes aria-hidden, inert, a dialog, tab, accordion, or application state.

`show-when` value	Visible for
Omitted or `either`	The selected live human rep or AI Stand-in. This preserves existing behavior.
`rep`	A selected live human rep only.
`standin`	A selected AI Stand-in only.
Empty or another value	Nothing. Invalid values fail closed.

Attributes and content

Attribute or content	Effect
`hidden`	Recommended in the original HTML on either the button or its dedicated reveal wrapper so content does not flash before custom-element upgrade.
`show-when`	Optional display filter: `either` (the default), `rep`, or `standin`. Empty and unsupported values fail closed.
Default slot	The visible button label. Long text is kept on one line and truncated when necessary.
`avatar`	Shows the available responder’s avatar; a Stand mascot fallback appears when no usable avatar URL exists.
`message`	Supplies the opening greeting for a new session. Before the visitor’s first message, it replaces the greeting of an earlier open. An existing session keeps its transcript.
`prompt`	Adds context when a new session is created, if this button was the last chat opened before the visitor’s first message; it is not displayed as visitor text and does not update an existing session.
`analytics-id`	Adds a placement label to the activation event.
`class` and `style`	Apply ordinary host-element styling; exposed shadow parts support internal styling.

Availability and activation sequence

The component looks for window.StandChat; if it is not ready, it retries while the element remains connected.
It registers whenAvailable(...) and remains gated when no responder is found or the selected responder does not match show-when.
Each button evaluates the shared availability independently, so several buttons can use different display rules and opening messages on one page.
If multiple matching buttons or cards share one marked wrapper, the first match reveals it; every mismatched component remains internally hidden.
On click, it checks isAvailable() again before calling openChat(...).
The opening request is attributed with source stand_button, interaction click, and the optional analytics ID.
Until the visitor sends a first message, a later button, card, launcher, or API open replaces this button’s greeting, prompt, and attribution. After that, a click reopens the current conversation unchanged.
Removing the element from the page clears its retry timer and availability subscription.

Styling surface

Part	Use
`::part(button)`	Style the native button wrapper, including background, border, padding, and hover treatment.
`::part(icon)`	Style the optional circular avatar wrapper.
`::part(label)`	Style the slotted label wrapper.
Host `class` or `style`	Control placement, margins, and the component’s page-level layout.

When to use something else

Use stand-card when the invitation needs explanatory copy, media, a visitor text field, separate actions, or spotlight presentation.
Use the JavaScript API when an existing application component must open Stand or needs dynamic options that cannot be expressed as attributes.
A Stand button supplies a greeting and optional private prompt; it does not collect or submit the visitor’s first message.
The button does not override routing or reveal itself without a matching available responder.
A data-stand-reveal wrapper should be dedicated to Stand-controlled content. Do not use a hidden tab, modal, accordion, responsive duplicate, or framework-owned visibility container; external reveal is one-way and application rendering can reapply its own state.
Use separate marked wrappers when surrounding headings or copy are specific to a rep or Stand-in. A shared wrapper has OR semantics: any matching descendant can reveal its ordinary shared content.
The label and prompt attributes are authored in the host page and should not contain secrets.