Headless mode: your own button

A headless widget draws nothing while closed. Your page renders its own button and opens the widget through the JavaScript API; when open, the companion still appears in the corner with its character, because the conversation needs somewhere to be.

In the panel: Widget → Launcher → Launcher type → None (headless) (Widget settings); the button that opens it is your page’s own code, below.

Set it up

The owner picks None (headless) as the launcher type on the widget’s Launcher tab, or a page sets it:

<script>
  window.ShukaiConfig = { launcher: { type: "none" } };
</script>
<button id="ask" type="button">Ask the assistant</button>
<script>
  document.getElementById("ask").addEventListener("click", () => Shukai.open());
</script>

Shukai.open() is the only entrance. It works before the widget has mounted — calls are queued — so the button can exist from the first paint. Shukai.toggle() and Shukai.isOpen() let one button open and close. Setting launcher: { type: "none" } from a page replaces the owner’s whole launcher object, label and container included (the merge is shallow).

What the companion still draws

While open, the character is shown in the corner — hidden again on close — so the dock, the bubbles, the card and the composer have their anchor; it can be dragged like any launcher. The skin and colours are the owner’s (voiceCharacter, voiceOrbColor, orbColours). On close the widget hands focus back to the element that opened it, so a keyboard user lands on your button again.

What you give up

• No greeting teaser and no attract animation: there is no closed launcher to put them on.
• No launcher label: a headless launcher never shows one.
• No proactive findings at all: the tick that asks for them is not armed without a launcher.

Everything else is unchanged: page actions, voice, handoff, history, the events.

Styling your own button

The button is yours; the widget does not style it. If you want it to match the character, the widget’s theme tokens are readable from your page’s CSS the same way you set them — but the orb itself is not available as a separate component outside the widget.

When to use it

A page with a prominent «Ask» call-to-action of its own; an app whose top bar already has a help button; a design where a floating orb would fight the layout. For a public website the ordinary launcher is usually better: the character in the corner is what invites a visitor who did not come looking for help.