Dioxus Components

Accessible, customizable components for Dioxus.

---

Dioxus Components is a shadcn style component library for Dioxus built on top of the unstyled Dioxus primitives library. The unstyled primitives serve as the foundation for building accessible and customizable UI components in Dioxus applications. The styled versions serve as a starting point to develop your own design system.

Live preview: browse the component gallery at mentalgear.github.io/dioxus-components — individual component pages live at https://mentalgear.github.io/dioxus-components/component/<name>/.

Getting started

First, explore the component gallery to find the components you want to use.

Once you find a component, you can add it to your project with the Dioxus CLI. If you don't already have dx installed, you can do so with:

cargo install dioxus-cli

Then, you can add a component to your project with:

dx components add button

This will create a components folder in your project (if it doesn't already exist) and add the Button component files to it. If this is your first time adding a component, it will also prompt you to add a link to /assets/dx-components.css at the root of your app to provide the theme for your app.

Contributing

Project structure

This repository contains two main crates:

• dioxus-primitives: The core unstyled component library.
• preview: A Dioxus application that showcases the components from dioxus-primitives with shadcn-styled versions.

Adding new components

If you want to add a new component, you should:

1. If there is any new interaction logic or accessibility features required, implement an unstyled component in the dioxus-primitives crate. When adding components to the primitives library, ensure:
   • It adheres to the WAI-ARIA Authoring Practices for accessibility.
   • All styling can be modified via props. Every element should spread attributes and children from the props
2. In the preview crate, create a styled version of the component using shadcn styles. This will serve as an example of how to use the unstyled component and serve as the styled version dx components will add to projects.
3. Add tests in playwright to ensure the component behaves as expected.

Testing changes

The components use a combination of unit tests with cargo, css linting, and end-to-end tests with Playwright.

To run the unit tests for the dioxus-primitives crate, use:

cargo test -p dioxus-primitives

To run the CSS linting, use:

cd preview
npm install
npx stylelint "src/**/*.css"

To run the Playwright end-to-end tests, use:

cd playwright
npm install
npx playwright test

Most specs also run an axe-core static accessibility scan (valid ARIA, accessible names, unique landmarks, contrast, heading order, …) via the shared playwright/axe.ts helper — see dev-docs/conformance-harness.md, "axe (static rules)", for what it covers versus the behaviour oracles and its exclusion policy.

Local-only Playwright configs, for driving the suite against an already-running dx serve/dx run server instead of letting Playwright's own webServer block manage one: baseline.local.config.ts (full-suite runs), xvfb.local.config.ts (headed Chromium under a virtual X server, for tests that need a real, space-reserving scrollbar rather than headless Chromium's 0-width one), and ssg.local.config.ts (points at a plain static file server serving the fullstack-SSG-prerendered build rather than the dev server — see dev-docs/conformance-harness.md, "Hydration/deployment parity", for the full build-and-serve recipe this covers, including oracle/hydration-parity.spec.ts). When running any of these under root (as in a container), the touch/mobile-emulation oracle specs need Chromium launched with --no-sandbox — see baseline.local.config.ts's launchOptions for the pattern.

Several source-level guard scripts enforce conventions that would otherwise regress one component or change at a time. Some run in CI (.github/workflows/main.yml: check-cfg-axis.sh, check-hooks-in-closures.sh, check-self-subscribing-effects.sh, check-css-logical-properties.sh), and all of them are cheap enough to run on every relevant change locally, CI job or not:

# preview/ markup composes only themed wrappers (crate::components::*),
# never a raw dioxus_primitives:: component directly -- see
# dev-docs/preview-composition.md for why this matters.
scripts/check-preview-composition.sh

# rendered markup/component structure/attribute choice splits on the `web`
# Cargo feature, never on `target_family = "wasm"` -- see
# dev-docs/recommended-implementations.md, Caveat 1, for the production
# incident this guards against.
scripts/check-cfg-axis.sh

# every themed component's shipped classes are namespaced
# dx-<component>[-...], the collision-safety property #[css_module]
# hashing used to provide -- see dev-docs/backlog.md row 32.
scripts/check-dx-class-prefix.sh

# a themed stylesheet may not hard-code a value that exactly matches a
# design token -- see dev-docs/backlog.md row 31b.
scripts/check-css-literals.sh

# no Dioxus hook is called inside the closure passed to another hook
# (use_context_provider, use_hook, use_memo, use_effect, use_callback,
# use_signal, use_resource, use_future) -- that panics at runtime
# ("hook list is already borrowed") with nothing at compile time to catch
# it. See dev-docs/backlog.md row 74 for the Navigation Menu incident this
# guards against.
scripts/check-hooks-in-closures.sh

# inside a use_effect closure, no signal is read with tracked syntax
# (x() / x.read()) and also written (x.set(...) / x.write()) -- that
# re-subscribes the effect to a value it just changed itself. See
# dev-docs/backlog.md row 73 for the Drawer drag-hang incident this
# guards against.
scripts/check-self-subscribing-effects.sh

# a themed stylesheet may not hard-code a physical inline-axis CSS value
# (margin-left/right, left/right, border-*-left/right*, text-align: left/
# right, a non-zero translateX(), ...) where a logical property would
# express the same rule and mirror correctly under dir="rtl" -- see
# dev-docs/backlog.md row 13. Two escape hatches: any rule selector
# mentioning `data-side=` (a screen-geometry fact, not a reading-direction
# one), or a `/* rtl-physical: <reason> */` comment -- see the script's own
# header for the full allowlist.
scripts/check-css-logical-properties.sh

Running the preview

To test your changes, you can run the preview application. For a desktop build, use:

dx serve -p preview --desktop

or for the web build:

dx serve -p preview --web

Deploying the preview / docs site

GitHub Pages is configured to serve straight from main's /docs folder — there is no CI build step. To publish a new preview build:

scripts/deploy-preview.sh

This builds the preview app in release mode and overwrites /docs with the output. Review the result (git status, git diff --stat -- docs), then commit and push to main.

License

This project is dual licensed under the MIT and Apache 2.0 licenses.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this repository, by you, shall be licensed as MIT or Apache 2.0, without any additional terms or conditions.