Script tag

Add ReadingVox to any website

One script tag adds a listen button with word-by-word highlighting to every page. It works anywhere you can edit the HTML template: static sites, Webflow, Squarespace, Shopify, React, Next.js, Vue, and more.

About 5 minutesNeeds: Someone who can edit your site's HTML templateFree plan, no card

Before you start

  • A ReadingVox account. Sign up free; no card needed.
  • Access to your site's HTML template (or a “custom code” / “footer code” setting in your site builder).
  • On WordPress? Use the WordPress guide instead.

Install steps

  1. Step 1: Create an API key

    In your dashboard, open API Keys, click Create New Key, give it a name (like your site name), and click Create key. Copy the key right away: for your security we store only a hash of it and can't show it again.

    readingvox.com/dashboard/keys

    Create a new API key

    Name
    My blog
    Create key
    (Step marker 1)Your new API key (copy it now)
    rv_live_3f9c…
    1. Marker 1: Copy the full key. It's shown only once; if you lose it, create a new one.

    Illustration — your screen may look slightly different.

  2. Step 2: Add your domain to the key

    Open Domains, type your site's domain (for example example.com), pick the key, and click Add Domain. Your key only works on domains you add, so it's safe to have in your page source. Use *.example.com to cover subdomains; if visitors use both example.com and www.example.com, add both. localhost always works for testing.

    readingvox.com/dashboard/domains

    Add an allowed domain

    (Step marker 1)Domain
    example.com
    API key
    My blog (rv_live_3f9c…)
    (Step marker 2)Add Domain
    1. Marker 1: Your site's domain, without https:// or a path.
    2. Marker 2: Add Domain. It works right away; there's no verification step.

    Illustration — your screen may look slightly different.

  3. Step 3: Paste the script tag before </body>

    Add this line to your site's template, just before the closing </body> tag, with your key in place of YOUR_API_KEY. In a site builder, use its footer or “before body end” custom code setting.

    your template
    <script src="https://readingvox.com/widget.js" data-key="YOUR_API_KEY" data-voice="heart" async></script>
    The script loads with async: it never holds up your page, even if ReadingVox were slow or down, and its reader tools load only when a visitor opens the toolbar.

Options (data-* attributes)

Add any of these to the script tag. Everything except data-key is optional.
example with options
<script
  src="https://readingvox.com/widget.js"
  data-key="YOUR_API_KEY"
  data-voice="heart"
  data-mode="page"
  data-color="#0b2545"
  data-tools="play,fontSize,screenMask,dictionary"
  async
></script>
Script tag options
AttributeValuesWhat it does
data-keyyour API keyRequired. Also accepted as data-api-key.
data-voiceheart (default), michael, lily, leo, mia, theoThe voice used to read your pages. Visitors can pick another in the toolbar's Settings.
data-speed0.5 – 2 (default 1)Starting reading speed.
data-modehighlight (default), page, blockhighlight: visitors select text to hear it. page: one player for the whole page. block: play buttons on content blocks.
data-selectorscomma-separated CSS selectorsWhich parts of the page are read. Default: article, main, [role="main"], .content.
data-toolscomma-separated: play, simplify, vocabSimplify, pageTheme, fontSize, fontSelector, screenMask, magnifier, screenshotReader, dictionary, translate, summary, download, clickListen, formReader, settingsWhich toolbar tools to show. Default: all of them. The play controls always show, and screenshotReader only works in the Chrome extension.
data-langauto (default), or a language code like esLanguage of your content. auto follows the page's lang attribute; Spanish, French, Italian, Portuguese, Hindi, Japanese and Chinese get natural voices.
data-ui-langauto (default), or a code like es, ar, viLanguage of the toolbar itself (29 languages). auto follows the visitor's browser.
data-documentstrue, false (default)Add a Listen button after links to PDFs, which opens them in a reader view.
data-themeauto (default), light, darkPlayer and toolbar color scheme.
data-colora CSS color, e.g. #0b2545Accent color for buttons and highlights.
data-positiontop (default), bottomWhere the toolbar sits.
data-toggle-positionbottom-right (default), bottom-left, top-right, top-leftWhere the floating ReadingVox button sits.
data-show-toggletrue (default), falseShow the floating button.
data-pulsetrue (default), falseGently pulse the button for first-time visitors.
data-always-showtrue, false (default)Keep the player visible instead of opening it on demand.
data-presetcanvas, moodle, noneLMS presets that read only course content. Set automatically by our LMS installs; none turns off LMS auto-detection.
data-auto-inittrue (default), falseSet false to start the widget yourself with new ReadingVox({...}) in JavaScript.
data-debugtrueLog setup details to the browser console while you test.

Every plan gets the full toolbar. Free and Starter use two standard voices (Ava and Sam); Pro and Business get all 6. Translation depends on your plan (see pricing).

Check that it works

  1. Open a page on your live site (on the domain you added).
  2. Look for the ReadingVox button in the bottom-right corner and press play.
  3. Not there? Add data-debug="true" to the tag, reload, and open your browser's developer console for ReadingVox setup messages.

What happens at your monthly limit

Website plans include a monthly allowance of characters turned into new audio. Replays of cached audio are always free. Going over never breaks your site:

  • Emails at 80% and 100% of your allowance, so you can plan ahead.
  • 20% grace buffer on paid plans: natural-voice audio keeps being generated until you reach 120% of your allowance.
  • After the limit (plus grace), audio that already exists keeps playing in the natural voice. New sentences are read with the visitor's built-in browser voice instead. Visitors never see an error.
  • Resets monthly. Natural-voice audio for new sentences resumes when your allowance resets.
  • Upgrade any time from the Billing page of your dashboard. The higher allowance applies immediately.
  • Launch bonus: in your account's first 30 days, your allowance is doubled, so you can voice your existing back catalog once. After that it's cached for every visitor.
  • No overage charges. We never bill you for going over.

Institution plans work the same way under their fair-use caps. Pilots are limited to 2M characters a month and 200 Chrome extension seats until the first payment.

Troubleshooting

The button doesn't appear

  • Domain not added. The domain in the browser's address bar must be on your key in Domains, including www. if visitors use it.
  • Wrong or revoked key. Check the key in the tag matches an active key on the API Keys page.
  • Cached page. Clear your site's or CDN's cache, then reload with Ctrl+Shift+R (Cmd+Shift+R on a Mac).
  • Script blocked. If your site sends a Content-Security-Policy header, allow https://readingvox.com for scripts and connections.
  • Nothing to read. If your content isn't inside article or main, point data-selectors at it.

It reads with a different, robotic-sounding voice

You've passed your monthly allowance, so new sentences use the visitor's built-in browser voice. Already-generated audio keeps its natural voice. See what happens at your monthly limit; upgrading takes effect immediately.

It reads the menu, footer, or comments

Set data-selectors to the element that holds your main text, for example data-selectors=".post-body". Navigation, footers, and sidebars are skipped by default.

Remove ReadingVox

  1. Delete the script tag from your template and publish.
  2. Optional: Revoke the key on the API Keys page, and cancel a paid plan on the Billing page.

Data & privacy

What ReadingVox receives

  • The text a visitor chooses to play or translate, so we can turn it into audio.
  • Standard request details: IP address, browser type, and the page address.
  • Your API key, which identifies your account.

What it doesn't

  • Visitor names or email addresses.
  • Anything from pages where the script isn't installed.

Sub-processors, retention, FERPA terms, security answers, and documents (DPA, VPAT, HECVAT Lite, W-9).

For IT & procurement

Other install guides

Stuck on a step?

Email [email protected] with your platform, the step you're on, and a screenshot of what you see. We answer every message.

Email support