Contributing

Bug reports, accessibility findings, docs fixes and pull requests are all welcome. Please read the Code of Conduct first, and report security issues as described in SECURITY.md instead of opening an issue.

SetupCopy Anchor Link

You need Node 22 or newer.

npm install

npx playwright install chromium

npm run dev

npm run dev starts the playground on Vite. It is the quickest way to see a change. The Playwright tests run against it too.

WorkflowCopy Anchor Link

1. Open an issue first for anything larger than a small fix, so we can agree on the approach.
2. Write the failing test first, then the change. Unit and integration tests live next to the code in src/*.test.ts(x). Browser tests live in e2e/.
3. Keep the package free of runtime dependencies. Anything the site or docs need goes in devDependencies.
4. Every visible string, icon, color and timing must stay replaceable through labels, icons, render or a --eg-* variable.
5. Run the checks before opening a pull request.

npm run format

npm run lint && npm run typecheck && npm run test && npm run e2e

npm run build && npm run size && npm run check:package

Working on the docsCopy Anchor Link

This site lives in docs/, a Next.js app built with Fumadocs, rendered on the server and deployed to Vercel with docs as the root directory. proxy.ts sets a per-request Content Security Policy. It imports the library straight from src/, so the demos always run the code in your branch, and the prop tables are generated from src/types.ts.

npm install --prefix docs

npm run dev --prefix docs

Pages are MDX files in docs/content/docs, and the sidebar order is in meta.json there. Two components are available in every page:

• <Demo /> renders a live gallery. Pass plain lightbox props, set (images, media or player), count, and preset for props that need functions.
• <HashDemo prefix="..." /> does the same with useLightboxHash.
• <GridsDemo /> renders a grid. Pass layout, switcher, filter, lightbox and count.

Write prop tables with <auto-type-table path="src/types.ts" name="..." /> instead of by hand, so they cannot drift from the code.

Code styleCopy Anchor Link

• TypeScript in strict mode. Public exports have explicit types and a doc comment.
• Only documentation comments. A short comment is fine when it explains a non-obvious reason the code cannot show.
• Animations use transform and opacity only and respect prefers-reduced-motion.
• No em dashes in prose, code comments or commit messages.
• Commit messages follow Conventional Commits (feat:, fix:, docs:, test:, chore:).

AccessibilityCopy Anchor Link

Changes to the viewer must keep it usable with a keyboard and a screen reader. Check focus order, focus return, labels and announcements in a real browser, and add an end-to-end test when behavior changes.

ReleasesCopy Anchor Link

Maintainers release by publishing a GitHub release, which runs the publish workflow and puts the version on npm.