What you need
TYPO3 14.3 or 13.4 LTS (PHP 8.2 to 8.5) or TYPO3 12.4 with ELTS (PHP 8.1 to 8.4) and a backend account with access to site management. To install, you need Composer or, without Composer, access to the extension module. In Accessonaut, first create a project with your actual website domain and open the installation page in the project.
Step by step
- Install the extension
accessonautfrom the section “The TYPO3 extension” below: with Composer, or without Composer under Admin Tools → Extensions → “Upload Extension”. In Composer mode, then runvendor/bin/typo3 extension:setup. - TYPO3 13.4 and 14.3: open Site Management → Sites, edit your site and add “Accessonaut reading-aid widget” under Sets. Alternatively, add
accessonaut/widgetto the dependencies of your site package’s set. - Open Site Management → Settings, choose your site and the category “Accessonaut reading aids”. Enter the public project ID from the installation page of your Accessonaut project and keep the service address https://accessonaut.com. In TYPO3 12.4, use the “Accessonaut” tab of the site configuration instead; it works in all versions.
- Read the note on the external service, switch the widget on and save. The change applies from the next page request, including pages from the TYPO3 page cache. Then check several public pages in a private window.
The TYPO3 extension
The extension “Accessonaut reading aids” (extension key accessonaut, Composer package accessonaut/typo3-accessibility) adds the script for you, without template or TypoScript changes. It runs on TYPO3 14.3 and 13.4 LTS as well as 12.4 (ELTS only) and starts switched off in every site. Only when you switch it on and enter a valid project ID does the browser load anything from the service. The widget never appears in the backend.
accessonaut_1.0.0.zip
SHA-256 checksum · Licence: GPLv2 or later
Publication on Packagist and in the TYPO3 Extension Repository (TER) is prepared. Until then, install the ZIP file: without Composer under Admin Tools → Extensions → “Upload Extension”, with Composer as a local package:
mkdir -p packages
cp ~/Downloads/accessonaut_1.0.0.zip packages/
composer config repositories.accessonaut artifact ./packages
composer require accessonaut/typo3-accessibility:^1.0
vendor/bin/typo3 extension:setupWithout the extension or bundle you can still add the embed code yourself. It is shown in the next section; the common questions further down explain how.
What the embed looks like
Use the ready-made code from your project. The example needs your real project ID and the publicly reachable service address.
<script src="https://accessonaut.com/widget.js"
data-project-id="YOUR_PROJECT_ID"
data-language="en" defer></script>Match the design to your website
In your Accessonaut project, open “Reading-aid widget”. Five templates and a live preview help you with the design: colours, fonts, menu width, corners, shadows, an icon or labelled opener and your own texts. Position and edge spacing can be set separately for desktop and smartphone. After saving, your existing embed code picks up the project design automatically; the public configuration is cached for up to one minute.
In the WordPress plugin you can choose local settings instead. These take priority over the project design. Design options are available on all plans. On the Free plan, the Accessonaut notice stays visible. Your visitors’ personal reading settings take priority over design defaults.
Keep in mind
Use exactly one installation method and remove an older entry in page.footerData or in the template. If the extension already finds a script of the same service on a page, it does not add a second one. You need to clear static page caches, proxies and CDNs yourself. If every site has its own domain, each needs its own Accessonaut project. An active Content Security Policy in the frontend must allow your service origin.
Common questions about TYPO3
How do I add the widget without the extension?
Via TypoScript in your site package: add a free entry to your PAGE object, for example page.footerData.1729 = TEXT, and set the unchanged embed code as page.footerData.1729.value. TYPO3 outputs footerData at the end of the page. Then clear the frontend caches via the lightning bolt icon. If you install the extension later, remove this entry.
How do I set up several sites?
The extension reads its settings per site. Switch the widget on in every site that should show it. If every site has its own domain, create one Accessonaut project per domain and enter its project ID in the matching site. The languages of a site share its settings.
What do I need to do with an active frontend CSP?
If security.frontend.enforceContentSecurityPolicy is active, extend the site’s policy in config/sites/<site>/csp.yaml. Use mutations with mode: "extend" to add your service address to the script-src and connect-src directives. The widget also inserts style elements without a nonce. So check whether style-src allows inline styles.
Do I need a separate setting for each language?
No. With the language “auto”, the widget follows your page’s lang attribute as long as no fixed language is saved in the project design. It speaks German, English and Spanish. A fixed language in the extension applies to all pages of this site and takes precedence over the project design.
How do I remove the widget again?
Switch it off in the site settings or in the “Accessonaut” tab. This applies from the next page request. To remove the extension completely, use composer remove accessonaut/typo3-accessibility or uninstall it in the extension module. Then clear static caches, proxies and CDNs.
If something does not work
The script is missing from the page source.
Cause: The widget is not switched on in this site, the project ID has an invalid format or the service address is not an HTTPS address. If the site includes the site set, only its settings apply, not the “Accessonaut” tab.
Fix: Check the switch, the project ID (20 to 40 lowercase letters and digits) and the service address in exactly the site that serves the page. Clear static caches and CDNs.
The browser console reports a CSP violation.
Cause: TYPO3’s frontend policy does not yet allow your service address.
Fix: Add it to the site’s csp.yaml and clear the caches.
An older embed keeps working and changes in the extension have no effect.
Cause: The site package still contains an entry with the embed code, for example in page.footerData. The extension then does not add a second script.
Fix: Remove the old entry and choose “Flush frontend caches”.
Check the installation
- Open the public website in a private window. The widget appears exactly once.
- Reach the button with the keyboard. Open the panel, change the text size and close it again.
- Check the homepage, a subpage, a form and the mobile view. The widget must not cover any important controls.
- In the Network tab, check that widget.js and the project configuration load from your service address. If there are errors, check the domain, project ID and CSP.
- For Free projects, the visible Accessonaut notice remains part of the widget. Permissions come from your project.
Privacy and limits
When it loads, the visitor’s browser fetches the script and the project configuration from the Accessonaut service. This involves the IP address, browser request data and the website hostname. Display preferences are stored locally in the browser. Cover the integration in your privacy notice and check your specific configuration.
The reading aids do not guarantee conformance. Also check barriers in the source code and complete user journeys, both automatically and manually.