Getting Started

Get up and running with compa11y in your project in under a minute.

Installation

React

Install the React package for component-level primitives and hooks.

npm install @compa11y/react

Core (framework-agnostic)

Install the core package for low-level accessibility primitives.

npm install @compa11y/core

Web Components (CDN)

Use the Web Components package via CDN for any HTML page.

<!-- Via unpkg -->
<script src="https://unpkg.com/@compa11y/web"></script>

<!-- Via jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@compa11y/web"></script>

Quick Start

React Example

App.tsx

import { useState } from "react";
import { Dialog } from "@compa11y/react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>

      <Dialog open={open} onOpenChange={setOpen}>
        <Dialog.Title>Welcome</Dialog.Title>
        <Dialog.Description>
          This dialog has focus trapping, Escape to close,
          and screen reader announcements built in.
        </Dialog.Description>
        <Dialog.Actions>
          <button onClick={() => setOpen(false)}>Close</button>
        </Dialog.Actions>
      </Dialog>
    </>
  );
}

Web Components Example

index.html

<script src="https://unpkg.com/@compa11y/web"></script>

<compa11y-dialog trigger="open-btn">
  <span slot="title">Welcome</span>
  <span slot="description">
    This dialog is fully accessible out of the box.
  </span>
  <div slot="actions">
    <button>Close</button>
  </div>
</compa11y-dialog>

<button id="open-btn">Open Dialog</button>

Package Structure

compa11y is organized as a monorepo with three packages that share the same accessibility primitives.

@compa11y/react

React components and hooks. Compound component patterns, TypeScript-first, tree-shakeable imports. Peer dependency: React 18+.

@compa11y/core

Framework-agnostic JavaScript/TypeScript primitives. Focus management, keyboard handling, screen reader announcements, and ARIA utilities.

@compa11y/web

Web Components for vanilla HTML/JS. Available as ESM, UMD, or IIFE via CDN. Use custom elements like <compa11y-dialog> in any page.

TypeScript

All packages include TypeScript declarations out of the box. No additional@types packages needed.

Styling

compa11y components are unstyled by default. They provide structural styles only (display, positioning for overlays) and leave visual styling to you.

CSS Variables

Every component exposes CSS custom properties (e.g., --compa11y-switch-bg) for quick theming without writing complex selectors.

styles.css

.my-switch {
  --compa11y-switch-bg: #d1d5db;
  --compa11y-switch-checked-bg: #10b981;
  --compa11y-switch-thumb-bg: white;
  --compa11y-switch-width: 3rem;
  --compa11y-switch-height: 1.75rem;
}

/* Style via data attributes */
[data-compa11y-tab][data-selected="true"] {
  border-bottom: 2px solid #10b981;
  color: #10b981;
}