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.

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.

Two source-level guard scripts run in CI and are cheap enough to run on every relevant change locally:

# 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

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.