Toolbelt is a headless and unstyled component library for common accessibility patterns, built on top of Alpine.js. The library is tech-agnostic. As long as you're producing HTML, Toolbelt is compatible.
Upstatement builds websites for various brands and with various technologies but accessibility conformance is a constant across our work. Toolbelt is meant to bridge the knowledge gap in our web accessibility practice by providing components that adhere to WCAG and WAI-ARIA patterns out of the box, regardless of the technology stack we use.
There are two ways to install Toolbelt. In either case, it might be helpful to read through how installation works for Alpine core. The following guide skips some details that are already covered in Alpine’s documentation.
The easiest way to install Toolbelt is to include its CDN link. Because Toobelt is an Alpine plugin, you will have to include Alpine as a dependency. In addition, the Focus plugin is a required dependency for Toolbelt. Notice that Toolbelt and Alpine plugins come before Alpine core.
Include the following script tags in your <head>:
<head>
<!-- Toolbelt -->
<script
src="https://cdn.jsdelivr.net/npm/@upstatement/toolbelt@1.0.0-alpha.1/dist/plugin.cdn.js"
defer
></script>
<!-- Focus plugin (Toolbelt dependency) -->
<script
src="https://cdn.jsdelivr.net/npm/@alpinejs/focus@3.14.7/dist/cdn.min.js"
defer
></script>
<!-- Alpine core -->
<script
src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.7/dist/cdn.min.js"
defer
></script>
</head>If you prefer bundling Toolbelt and its dependencies in your own Javascript bundle, you can install these packages from the npm registry.
-
Install the following packages:
npm install alpinejs @alpinejs/focus @upstatement/toolbelt
-
Import and initialize the packages like so:
import Alpine from "alpinejs"; import focus from "@alpinejs/focus"; import toolbelt from "@upstatement/toolbelt"; window.Alpine = Alpine; Alpine.plugin(toolbelt); Alpine.plugin(focus); Alpine.start();
This repository hosts the Astro Starlight documentation site and library files for Toolbelt.
toolbelt
├── public # (Astro) Asset files
├── scripts # (Toolbelt) Build scripts
├── src
│ ├── components # (Astro) Components
│ ├── content # (Astro) Markdown documentation files
│ └── lib # (Toolbelt) Library files
│ ├── __tests__ # (Toolbelt) Test suites
│ ├── builds # (Toolbelt) Build files (e.g. CDN, ESM)
│ └── toolbelt # (Toolbelt) Components
├── tailwind.config.mjs # (Astro) Tailwind configuration
└── vitest.config.js # (Toolbelt) Vitest configuration
- Install and use specified Node version.
nvm use- Install repository dependencies.
npm install- If you're working on the Astro site, start the local dev server. You can view the website at
localhost:3000
npm run dev- If you're working on Toolbelt, start the tests on watch mode. This is to encourage test-driven development (TDD).
npm run test:watch| Command | Action |
|---|---|
npm install |
Installs dependencies |
npm run dev |
Starts local dev server at localhost:3000 |
npm run build |
Build the production site to ./dist/ |
npm run test |
Run tests |
npm run test:watch |
Run tests on watch mode |
npm run package:build |
Build the production packages |