Components
Getting started with components
Install jx_cli, list the components folder, and use them like any Jaspr component.
Installation
The components ship inside jx_cli: one dependency gives you the compiler, the CLI and the components.
dart pub add jx_cli
Coming from jx_ui
The components need jx_cli 0.0.3 or later. They used to ship as the separate package jx_ui, now discontinued: replace it with jx_cli and import
package:jx_cli/ui.dart.
Configuration
The CLI only compiles the classes it finds. Add the components folder to packages
in jx.yaml, so the classes used inside the components reach your stylesheet:
content:
- lib
packages: [jx_cli/ui]
output: web/jx.css
Then build the CSS once, or keep it in sync while you work:
dart run jx_cli build
dart run jx_cli watch
A first component
import 'package:jaspr/jaspr.dart';
import 'package:jx_cli/ui.dart';
class Welcome extends StatelessComponent {
const Welcome({super.key});
@override
Component build(BuildContext context) {
return JxCard(
title: 'Welcome',
description: 'Your workspace is ready.',
footer: [JxButton([.text('Create a project')])],
[const JxBadge('New', tone: JxTone.info)],
);
}
}
Welcome
Your workspace is ready.
New
Components with callbacks (onClick,
onInput, onChange) need to run in the browser: use them inside a
@client component or a page that hydrates.
Theming
The components use five color families of the theme: blue
for actions and focus, gray
for text and surfaces, red,
green and yellow
for the tones. Redefine them in jx.yaml
and every component follows:
theme:
extend:
colors:
blue:
100: '#EDE9FE'
500: '#8B5CF6'
700: '#6D28D9'
800: '#5B21B6'
900: '#4C1D95'
| Token | Used for |
|---|---|
blue-700 |
Primary buttons, checked controls, progress bars, links in tables. |
blue-500 |
Focus ring, focused field border. |
blue-100 |
Info badge and alert, row hover. |
gray-900 / gray-100
|
Strong text in light and dark mode. |
gray-100 / gray-700
|
Borders of cards, tables, dialogs. |
red-*, green-*, yellow-*
|
Danger, success and warning tones; field errors. |
The focus ring, strong text and surface borders are shared tokens inside the components, so a button, a field and a dialog always focus and outline the same way.
Customizing one instance
Every component takes classes, appended after its own classes. Later classes win, so you can override a default without fighting specificity:
JxButton(classes: 'w:full md:w:auto', [.text('Continue')])
JxCard(title: 'Plan', classes: 'sh:none bc:blue-500', [...])
JxSkeleton(classes: 'w:10 h:10 br:full')
Dark mode
Surfaces, text and borders have dark:
variants and follow the system setting. Toggle your system theme to see the previews switch.
Design principles
-
Native first:
<button>,<dialog>,<details>,<select>, real checkboxes. The browser handles focus, keyboard and announcements. - No JavaScript needed to render: modals, drawers and accordions open with HTML alone.
-
Visible focus on keyboard use only (
focus-visible), never removed. - Motion stops when the system asks for reduced motion.
- Touch targets of at least 40 px on buttons and controls.
- Your state, your data: tables and pagination report events, you decide what to render.