Frontend API

Since 1.30.0. What themes and site scripts may rely on; changes are marked Breaking in the changelog.

Site settings

Setting	Effect
ntai.a11yWidget.primaryColor / primaryColorDark	Main colour of widget, switches, sliders, focus outline and read-aloud highlight (light / dark chrome). Empty = default blue.
ntai.a11yWidget.address	sie (default) or du for the German texts.
ntai.a11yWidget.introText / tooltipText	Own wording for the panel introduction and the first-visit hint.
ntai.a11yWidget.hideWhen	CSS selector; while it matches, the widget is hidden (e.g. an open full-screen chat).
ntai.a11yWidget.hideMedia	Since 1.31.0. Media query, e.g. (max-width: 767px). With hideWhen: hidden when both match; without: always hidden at that viewport.
ntai.tts.scope	Reading area, a list tried in order (default #maincontent, main, [role=main]).
ntai.tts.readImageAlt	Read images with a text alternative as "Bild: …" (default on).
ntai.tts.expandCollapsed	Open accordions, <details> and hidden="until-found" for reading and close them again afterwards (default on).

CSS custom properties

Colours on :root, position on .nt-a11y-widget (also inside media queries): --nt-a11y-primary, --nt-a11y-primary-dark, derived --nt-a11y-primary-contrast, --nt-a11y-primary-tint, --nt-a11y-on-tint, --nt-a11y-primary-tint-dark, --nt-a11y-on-tint-dark, --nt-a11y-focus, --nt-a11y-focus-dark, --nt-tts-highlight; since 1.31.0 --nt-a11y-primary-dark-contrast (text on the dark "on" mark), --nt-a11y-launcher-hover / --nt-a11y-launcher-hover-dark (launcher background on hover and focus), --nt-a11y-title-color / --nt-a11y-title-color-dark (panel title; the site's h2 colour is not inherited); --nt-a11y-offset-x, --nt-a11y-offset-y, --nt-a11y-z.

Markup

The container div.nt-a11y-widget is appended at the end of body and, since 1.32.1, is a named landmark (role="region", aria-label = panel title), so it can be found when navigating by landmarks. The reading bar div.nt-tts-bar is a named region as well.

Attributes

• html[data-nt-theme="dark"] – set by the dark-mode switch before the first paint; the page's dark design is the theme's job. "Highlight focus" then uses --nt-a11y-focus-dark. An operating system in dark mode does not make the page dark and therefore does not change the focus colour.
• html[data-nt-a11y-hidden] – widget hidden.
• [data-nt-tts] on a button – starts/stops reading; value = optional scope selector. Buttons added later: window.ntTts.wire().
• [data-nt-tts-skip] – element is not read aloud.

Events (on document, data in event.detail)

nt-tts:beforecollect (cancelable; scope, source, waitUntil(promise)), nt-tts:start (source: button/widget/click/api, blocks), nt-tts:segment (index, total, node, engine), nt-tts:pause, nt-tts:resume, nt-tts:stop (reason: user/end/error, since 1.34.0 also language), nt-tts:fallback (from, to, index, rest, status = always null so far), nt-tts:error (reason), nt-tts:clickmode (on; since 1.31.0, only on an actual change); nt-a11y:ready, open, close (since 1.31.0 only on an actual change), reset, nt-a11y:change (key, value, previous; own entries as custom:<id>), nt-a11y:language (lang; since 1.34.0, after a language change at runtime).

Global objects

window.ntTts (version 2): play(scope?, source?), pause(), resume(), stop(), toggle(scope?, source?), skip(±1), setVolume(), setRate(), setClickMode(), isPlaying(), onState(cb), wire(), getLang() (since 1.34.0).

window.ntA11y (version 1): open(), close(), toggle(), isOpen(), getPrefs(), setPref(key, value), hide(), show(), refresh(), registerToggle({ id, label, description?, isOn(), onToggle(on), position? }) – since 1.31.0 it returns a function that removes the entry –, unregisterToggle(id) (since 1.31.0), getLang() (since 1.34.0). Register own entries in a listener for nt-a11y:ready.

Language (since 1.34.0)

Widget and read-aloud read <html lang> on load and then watch lang and dir on the <html> element (MutationObserver). When a translation in the browser changes the language — nt-lingua in DOM mode or any other tool — both follow without a reload:

• The widget sets its texts again (panel, launcher label, tooltip, hints). Stored settings are kept, an open panel stays open, keyboard focus stays on the control. With dir="rtl" the container carries dir="rtl" and the panel is mirrored; the launcher keeps its configured corner.
• Read-aloud switches language and voice. A running playback ends (nt-tts:stop with reason: language); the next one reads in the new language.

Texts ship for de, en, fr, it, es, pt, nl, pl, ro, hr, sr (Cyrillic), bs, sq, el, tr, uk, ru and ar; other languages get English. The form of address (ntai.a11yWidget.address, Sie/du) applies to German only, the site's own texts (introText, tooltipText) only to the language the page was delivered in.

Browser test: NODE_PATH=<path>/node_modules node Tests/JavaScript/widget-language.cjs (Playwright, see file header).