# Accesserty UI Kit ![License: MIT](https://badgen.net/badge/license/MIT/orange) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Accesserty/UI-Kit) A library of **15 Web Components** with reusable semantics, keyboard interaction and focus handling. Use them in plain HTML or through the Vue/Nuxt and React 19/Next.js integrations. You still provide names, content and translations, and test the components in your application. Visit the [Accesserty UI Kit overview](https://accesserty.com/en/uikit/) for getting-started guidance, or try the [online Playground](https://accesserty.com/en/uikit/playground/) to explore component styles and copy examples. The API reference and local demos are available in [`demo/`](demo/index.html); framework setup is covered below. For plain HTML, copy one JavaScript file and load it with a ` I agree to the terms ``` Save the page next to the downloaded file and open it in a browser. You should see an email field and a checkbox. Their styles are included in the script. To change those styles, see [Styling](#styling). The same script works when you open the HTML directly from disk. Both full bundles register elements when loaded, keep internal variables out of the global scope and export no classes. Classic scripts and browser module side-effect imports are supported. Do not import these browser bundles in Node.js. For local file links, use relative paths such as `./index.html`, not `/index.html` (the filesystem root). See [Breadcrumbs in local HTML and SSR](docs/USAGE.md#breadcrumbs-in-local-html-and-ssr) for data bindings and navigation limits. The bundle registers every component. To ship only some of them, copy single files from [`dist/components/`](dist/components/). Each file works on its own, also in local HTML opened from disk: ```html ``` Use `components/input.min.js` for the minified file. The readable and minified files have the same behavior. `accordion.js` registers both `au-accordion` and `au-accordion-item`; `dropdown.js` and `tree.js` likewise register their item elements. Loading a file twice, or next to the full bundle, defines each element only once. Source files in `src/components/` are not the standalone distribution files: they may import shared modules. Use `dist/components/` for classic script tags. ### File selection and native forms ```html
Up to 5 files, 5MB each, 20MB total.
``` Replace `/upload` with your own server endpoint. The component selects files; it does not send network requests. The form submits them under `attachments`. Keep `enctype="multipart/form-data"` for a native file upload and validate files again on the server. The [local demo](demo/file-upload.html) does not upload files. Read [File selection and native forms](docs/USAGE.md#file-selection-and-native-forms) for selection limits, `File[]` values, events, disabled fields, validation and reset. The same reference covers the validity API shared by all seven form components. Pressing Enter in `au-input` does not submit the form. ## Framework Integration ### Vue 3 Copy the whole [`dist/`](dist/) folder into your project, for example as `src/vendor/accesserty/`. Define the elements and install the Vue plugin: ```js // main.js import './vendor/accesserty/accesserty-ui-kit.js' // defines the au-* elements import { createApp } from 'vue' import { AccessertyVue } from './vendor/accesserty/accesserty-ui-kit-vue.js' import App from './App.vue' createApp(App).use(AccessertyVue).mount('#app') ``` Configure the Vue compiler with the kit's `isCustomElement`. Do not use `tag => tag.startsWith('au-')`: that would bypass the seven form wrappers and prevent their `v-model` integration from working. ```js // vite.config.js import vue from '@vitejs/plugin-vue' import { isCustomElement } from './src/vendor/accesserty/accesserty-ui-kit-vue.js' export default { plugins: [vue({ template: { compilerOptions: { isCustomElement } } })] } ``` Then bind form components with `v-model`, as with native fields: ```vue Small Medium ``` | Component | `v-model` value | |---|---| | `au-input`, `au-textarea` | string; a number for `type="number"` when the text parses as one (`.trim`, `.number` and `.lazy` work) | | `au-checkbox`, `au-switch` | boolean; an array or `Set` of the checked boxes' `value`s; or `true-value` / `false-value` | | `au-radio-group` | the selected ``'s `value` as you bound it (`:value="2"` gives `2`), or `null` | | `au-rating` | number | | `au-file-upload` | array of `File`; set it to `[]` to clear the selection | Checkboxes can share an array, as with Vue's native `v-model`: ```vue ``` Typed radio values come from `` elements written directly inside the group (a `v-for` there is fine); options rendered by a child component of your own report their string value. Attributes, classes, listeners and slots pass through to the element. Your own `@input` and `@change` listeners still run. A template ref forwards element properties and methods: use `nameField.value.focus()` to focus the field, or `nameField.value.$el` when an API needs its DOM node. For non-form `au-*` elements, use ordinary attribute, property and event bindings. Existing explicit `:value` / `@input` bindings on form components also work. The adjacent `accesserty-ui-kit-vue.d.ts` types `v-model` through Vue's `GlobalComponents`. ### React and Next.js Copy the whole [`dist/`](dist/) folder into your project, for example as `vendor/accesserty/`. The form components have React counterparts with the usual form props, and `defineElements()` defines the `au-*` elements in the browser (they cannot be defined during server rendering): ```jsx 'use client' import { useEffect, useState } from 'react' import { AuInput, AuCheckbox, defineElements } from './vendor/accesserty/accesserty-ui-kit-react.js' export default function Signup() { const [email, setEmail] = useState('') const [agree, setAgree] = useState(false) useEffect(() => { defineElements() }, []) return (
setEmail(e.target.value)} /> setAgree(e.target.checked)} /> ) } ``` | Component | Controlled | Uncontrolled | Read in `onChange` | |---|---|---|---| | `AuInput`, `AuTextarea` | `value` | `defaultValue` | `e.target.value` | | `AuCheckbox`, `AuSwitch` | `checked` | `defaultChecked` | `e.target.checked` | | `AuRadioGroup` | `value` | `defaultValue` | `e.target.value` | | `AuRating` | `value` | `defaultValue` | `Number(e.target.value)` | | `AuFileUpload` | — | — | `e.target.value` (array of `File`) | `e.target` is the custom element. `AuCheckbox` and `AuSwitch` expose their `value` (`'on'` unless set), so you can collect checked values into an array. `AuInput` also exposes `valueAsNumber` and `valueAsDate`: ```jsx { const { checked, value } = e.target; setSources(list => checked ? [...list, value] : list.filter(x => x !== value)) }} /> setQty(e.target.valueAsNumber)} /> ``` A controlled value wins. If `onChange` does not update state, the wrapper restores the prop value on the next animation frame. Unlike a native React input, this moves the caret to the end of `AuInput` or `AuTextarea`. `ref` points at the element itself. Other props, `className` and children pass through. Call `defineElements()` once from a client effect, for example in a root layout's client component. The integration file starts with `'use client'`, so Next.js server components can render its exports without defining elements on the server. Other `au-*` elements are used directly as JSX tags: React 19 sets matching properties and attaches `on` + event-name props as listeners, for example ` setOpen(e.detail.open)}>`. The integration needs React 19. TypeScript declarations (`accesserty-ui-kit-react.d.ts`) sit next to the file and type every `au-*` tag, including event details such as `e.detail.open`. `accesserty-ui-kit.d.ts` types the elements themselves, so `document.querySelector('au-tabs')` knows `selectedIndex`. ### Other frameworks The kit uses standard custom elements. Only Vue/Nuxt and React 19/Next.js have tested integrations. Other stacks need their own checks for compilation, properties, events, forms and hydration; rendering the tags alone does not establish compatibility. ### Nuxt Copy the whole [`dist/`](dist/) folder into your project, for example as `vendor/accesserty/` (not `public/`), and add one module: ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: ['./vendor/accesserty/accesserty-ui-kit-nuxt.js'] }) ``` The module configures the Vue compiler, registers the `v-model` components for server and client rendering, and defines the elements in the browser. Use the components directly, including `v-model` on the form components listed under [Vue 3](#vue-3); no `` wrapper is needed. The server renders the element tags and their initial values. By default it also inserts declarative shadow roots for Accordion, Tabs and Breadcrumbs. Other components build their internals in the browser. See [Server rendering](#server-rendering). ### Server rendering Frameworks render the `` tags, attributes and initial values on the server. The kit's injector can also insert declarative shadow roots for `au-accordion` (including its items), `au-tabs` and `au-breadcrumbs`. The browser adopts these roots instead of rebuilding them. Other components, including the form controls, build their internals in the browser. No component class or browser bundle is safe to import in Node.js. Use the server-side integration modules instead. | Without JavaScript | `au-accordion` | `au-tabs` | `au-breadcrumbs` | |---|---|---|---| | Looks like the final component | yes | yes | yes | | Works | find-in-page and links open collapsed items where `until-found` is supported | only the selected panel is shown | links navigate | Insert roots into finished HTML after framework rendering. Do not write `