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.

Terminal
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:

jx.yaml
content:
  - lib

packages: [jx_cli/ui]

output: web/jx.css

Then build the CSS once, or keep it in sync while you work:

Terminal
dart run jx_cli build
dart run jx_cli watch

A first component

Dart
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:

jx.yaml
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:

Dart
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.