https://github.com/eldomagan/alpine-headless-ui
https://github.com/eldomagan/alpine-headless-ui
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/eldomagan/alpine-headless-ui
- Owner: eldomagan
- License: mit
- Created: 2025-12-16T13:39:36.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-16T13:41:28.000Z (7 months ago)
- Last Synced: 2025-12-20T03:35:52.345Z (7 months ago)
- Language: TypeScript
- Homepage: https://alpine-headless-ui.netlify.app
- Size: 147 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Alpine Headless UI
Headless, accessible UI primitives for Alpine.js, built with [`https://github.com/eldomagan/alpine-define-component`](https://github.com/eldomagan/alpine-define-component).
This library provides unstyled, behavior-only components inspired by:
* [Alpine UI components documentation](https://alpinejs.dev/components)
* [Zag.js behavior and accessibility patterns](https://zagjs.com/)
The goal is to give you composable Alpine components with correct state management, keyboard interactions, and ARIA attributes, while leaving all styling and markup control to you.
---
## Features
* Headless (no styles, no markup assumptions)
* Accessible by default (keyboard and ARIA patterns applied)
* Per-component imports
* Built on Alpine.js v3
---
## Installation
```bash
npm install alpine-headless-ui
```
## Getting started
### Register all components
```js
import Alpine from 'alpinejs'
import AlpineHeadlessUI from 'alpine-headless-ui'
Alpine.plugin(AlpineHeadlessUI)
Alpine.start()
```
This registers all available headless ui components globally.
---
### Register individual components
You can import and register only the components you need.
```js
import Alpine from 'alpinejs'
import dialog from 'alpine-headless-ui/dialog'
import menu from 'alpine-headless-ui/menu'
Alpine.plugin(dialog)
Alpine.plugin(menu)
Alpine.start()
```
This keeps your bundle size minimal.
---
## Component usage
All components follow the same pattern:
* A root element using `x-`
* Named parts using `x-:`
* Optional scoped sub-parts for repeated items
The exact HTML structure is up to you.
---
## Dialog
### Example
```html
Open Dialog
Dialog Title
This is a basic dialog example. Click outside or press Escape to close.
Close
```
### Behavior
* Focus is trapped inside the dialog when open
* Escape closes the dialog
* Focus returns to the trigger on close
* Backdrop click closes the dialog
* Body scroll prevented when open
---
## Accessibility
Alpine Headless UI components aim to follow WAI-ARIA authoring practices:
* Correct roles (`dialog`, `menu`, `combobox`, etc.)
* Keyboard interactions matching platform expectations
* Focus management on open and close
Behavior patterns are inspired by Zag.js state machines, adapted to Alpine idioms.
You are responsible for:
* Visual focus styles
* Animations and transitions
* Layout and spacing
## Credits
Inspired by:
- [Zag.js](https://zagjs.com/) - State machine patterns for accessible components
- [alpine-zag](https://github.com/TunkShif/alpine-zag) - Alpine.js integration with Zag.js
Created by:
- [Eldo Magan](https://github.com/eldomagan)
- [All Contributors](../../contributors)
## 📄 License
This project is open-sourced under the [MIT license](./LICENSE.md).