Voicegram

Customize the widget

Wire the recorder to your own buttons, suppress the floating bubble on specific pages, and tune the UI to match your site without touching the script source.

On this page

By default the widget renders a floating bubble in the bottom-right corner of every page. That is the right default for most sites, but you can customize the experience without touching any of the widget's source:

  • data-voicegram-trigger: a plain HTML attribute that turns any element on your page into a button that opens, closes, or toggles the recorder.
  • <meta name="voicegram-bubble">: a per-page meta tag that suppresses the floating bubble on that specific page.

Both are zero-JavaScript customizations. You can also drive the widget from JavaScript using the programmatic API for more advanced cases.

Attach the recorder to your own element

Add data-voicegram-trigger to any HTML element to make it open, close, or toggle the widget on click.

Trigger values

html
<!-- Bare attribute or "open" opens the modal -->
<button data-voicegram-trigger>Leave a voicegram</button>
<a href="#contact" data-voicegram-trigger="open">Contact us</a>

<!-- "close" closes the modal -->
<button data-voicegram-trigger="close">Close</button>

<!-- "toggle" opens if closed, closes if open -->
<button data-voicegram-trigger="toggle">Toggle</button>

Trigger behavior

  • Plain left-click only. Cmd, Ctrl, Shift, and Alt-click plus middle-click are ignored. This means <a href data-voicegram-trigger> still opens in a new tab on Cmd-click.
  • preventDefault() on the matched left-click. <a href> does not navigate. Submit buttons do not submit. The trigger controls the widget instead.
  • Native disabled is honored. <button disabled> blocks the click before the widget sees it.
  • Removing the attribute disables the trigger.
  • Disabled domains. If the domain is marked inactive in your Voicegram dashboard, data-voicegram-trigger clicks no-op, just like the bubble stays hidden.
  • Dynamically inserted elements work without any re-init step.
  • Disabled mid-flow. If the visitor is mid-recording or mid-verification, additional open clicks are no-ops so an in-progress session is not interrupted. The button itself stays clickable, but nothing happens.

Use an interactive element

  • <div data-voicegram-trigger> will not fire on keyboard activation and is not announced as interactive by screen readers. The widget auto-applies cursor: pointer to every [data-voicegram-trigger] element, but keyboard and screen-reader accessibility require using a <button> or <a href>, or adding tabindex="0", role="button", and an aria-label yourself.
  • Prefer <button> for actions and <a href> for navigation-style links.

Light DOM only

  • Triggers must be in the same document the widget script loaded into. Inside an <iframe>, only triggers in that frame's document fire.
  • Triggers inside a shadow root (open or closed) are not reliably detected. Keep triggers in the light DOM.

Examples

Custom CTA button on a contact page:

html
<button data-voicegram-trigger
        class="my-brand-button"
        style="font-weight: 700; padding: 12px 24px;">
  Leave us a voicegram
</button>

Inline link that opens the widget instead of navigating:

html
<p>Want to talk?
  <a href="/contact" data-voicegram-trigger>Send a Voicegram</a>
  instead.</p>

(Cmd-click still opens /contact in a new tab.)

Toggle button:

html
<button data-voicegram-trigger="toggle">Open or close recorder</button>

Suppress the floating bubble on a page

Add a meta tag to a page's <head> to hide the floating bubble on that specific page. Useful for product or catalog pages where you have your own custom triggers and do not want the bubble too.

html
<head>
  <meta name="voicegram-bubble" content="off">
</head>

Bubble suppression behavior

  • Default (no meta tag). Bubble shows.
  • content="off" (case-insensitive). Bubble hides.
  • Anything else (missing tag, empty, "auto", unknown values). Bubble shows.
  • Re-evaluated on every SPA route change (pushState, replaceState, popstate). Works in Next.js, Vue / Nuxt, Svelte, Astro, and other client-side routers.
  • data-voicegram-trigger keeps working on pages where the bubble is hidden, so a custom button can stand in for the bubble.

When to use it

  • Product or catalog pages where a custom CTA replaces the bubble.
  • Modal-heavy pages where the floating bubble would conflict with your UI.
  • Pages where the bubble would obscure important content.

Programmatic override

Calling window.__voicegram__.show() from JavaScript overrides the meta tag for the current page. Calling hide() keeps the bubble hidden across SPA navigation until you call show(). See the programmatic API for details.

Combine: hide the bubble, use your own button

The most common customization combo. Put the meta tag in <head> to suppress the default bubble, then drop one or more data-voicegram-trigger elements anywhere on the page:

html
<head>
  <meta name="voicegram-bubble" content="off">
  <script type="module" src="https://cdn.voicegram.io/w/pk_xxx.js"></script>
</head>
<body>
  <!-- Multiple triggers across the page -->
  <button data-voicegram-trigger>Sales</button>
  <button data-voicegram-trigger>Support</button>
  <a href="/contact" data-voicegram-trigger>General contact</a>
</body>

All three buttons open the same recorder. The bubble does not appear on this page.

Next steps

Need help? Email support@voicegram.io.