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

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="Happy to walk you through installation. How do you host your website today?"
  prompt="The visitor is reading installation instructions. First identify their website platform."
  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`	Replaces the ordinary opening greeting for this click.
`prompt`	Adds private context for the session; it is not shown as visitor text.
`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.
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.