Call a Custom Widget from HTML

How you “call” a custom widget from HTML

Think of three layers. The connection script loads GSpeech for the whole site. The widget in Cloud Console is the player definition (voice, chrome, selectors, URL rules). The mount in your HTML is the empty node where that player may appear.

• 1. Connection script — once per site (Integrations → Html Website), usually before </body>.
• 2. Published widget — Full / Button / Circle you create or customize in the console.
• 3. Mount in HTML — e.g. <div class="my_listen_btn"></div>; Render Element must be .my_listen_btn.
• Content Selector — CSS target for page text to narrate (or leave empty and use Content Text for stand-alone audio).

Rule of thumb: HTML never “imports” a widget by name. Matching Render Element + mount class is the call.

How to write id, class, and commas (no coding degree needed)

Content Selector, Render Element, and Exclude List use the same simple language. You only need two prefixes — then you can assemble spoken content in pieces and carve out junk with Exclude.

• id → # — in HTML id="article" → in GSpeech write #article (hash + the exact id).
• class → . — in HTML class="post-content" → write .post-content (dot + the exact class). If the element has several classes, one matching class is enough.
• Tag only — bare tag names work too: article, section, h1 (no # or .).
• Content Selector + commas — gather content in pieces in one field: #intro,.chapter-body,#summary. Matches are read in order — perfect when the page is split across several wrappers.
• Exclude List + commas — strip noise from that selection with the same syntax: #comments,.ads,.share-buttons. Excludes apply inside what Content Selector collected.
• How to find values — on the live page: right-click the block → Inspect. Look for id="…" or class="…", then type them with # or . in the console. Deep Exclude walkthrough: Exclude List & nospeech.

Three default mounts vs your own custom widget

Docs often show the three convenient mount classes because they ship ready with Cloud defaults. A custom widget is not a different product — it is the same Full / Button / Circle type with your Render Element (and usually your Content Selector).

• Default Full — mount <div class="gsp_full_player"></div> → Render Element .gsp_full_player.
• Default Button — .gsp_button_player mount + matching Render Element.
• Default Circle — .gsp_circle_player mount + matching Render Element.
• Your custom call — any class or id you own (e.g. #promo-listen or .footer_tts) → set that exact selector as Render Element on the widget you published.

WordPress shortcodes ([gspeech] / button / circle) are a different placement path for posts. On raw HTML there is no shortcode — only the mount + Render Element pair. See default shortcodes for WP only.

End-to-end: configure and call your custom widget

1. Create / open your website in the Cloud Console and confirm Global defaults in Settings (voice, language) — see Global vs custom.
2. Copy the Html Website connection script from Integrations and paste it once in your shared template before </body>. Deploy so every page that needs audio loads the script.
3. Create a Full / Button / Circle widget (or open an existing custom one). Give it a clear name so you recognize it later.
4. In the page HTML, add an empty mount where the player should appear — pick a unique class you will not reuse for unrelated UI. Example: <div class="my_custom_player"></div>.
5. On the widget, set Render Element to that exact selector: .my_custom_player (leading dot for a class; #id for an id).
6. Set Content Selector to what visitors should hear. One wrapper is fine (#main or .product-description). Or assemble pieces with commas: #intro,.body-copy,#summary. Use parent_class / self_class when the mount sits inside that content block.
7. Optional: Exclude List (also comma-separated, same # / . rules) for nav / ads / comments — e.g. #comments,.ads,.share-buttons. Optional: Allowed / Blocked Urls so this widget only runs where you want.
8. Set status to Published, Save, hard-reload the live HTML page, and confirm the player fills your mount and reads the right text.

Need audio with no surrounding page text (demo / kiosk style)? Leave Content Selector empty and fill Content Text instead — full walkthrough: Stand-alone player with Content Text.

Minimal HTML page that calls your widget

Below is the shape of a working page. Replace the connection script with yours from Integrations. The mount class must match Render Element on the published widget; Content Selector should target #article in this example.

• Mount in HTML — <div class="my_custom_player"></div> (empty).
• Widget Render Element — .my_custom_player.
• Widget Content Selector — #article.
• Connection script — your one-line Html Website embed before </body>.

Skeleton (comments show the mapping):

<!-- spoken content -->
<article id="article">…your text…</article>
<!-- player mount (Render Element = .my_custom_player) -->
<div class="my_custom_player"></div>
<!-- GSpeech connection script from Integrations -->

You can put the mount above the article, in a sidebar, or in the footer — Content Selector still points at #article, so layout chrome is not spoken. That layout pattern is also covered in Place a custom widget.

If the custom widget does not appear

1. Connection script loaded on that URL (View Source / Network).
2. Widget status is Published (not draft / disabled).
3. Mount exists on the page and class/id spelling matches Render Element exactly (including the leading . or #).
4. Content Selector finds real text (or Content Text is filled for stand-alone).
5. Allowed / Blocked Urls are not excluding this path.
6. Hard-reload after Save — HTML/CDN cache can keep an old shell briefly.

Full troubleshooting path: Player not showing.