Getting started

This guide takes you from an empty project to a rendered Lovelace component.

Requirements

  • React 19 and React DOM 19. The peer dependency range is ^19.0.0 and earlier versions are not supported.
  • A bundler or dev server that can import plain .css files. Vite, Next.js, and webpack with css-loader all qualify.

1. Install the package

1npm install @ada-cx/lovelace react react-dom

@ada-cx/lovelace is live on npm. Install the latest version. Before GA, any release can change or remove a component’s props. Read the release notes before you upgrade.

2. Import both stylesheets

Import both stylesheets once, at your app entry:

1import "@ada-cx/lovelace/tokens.css";
2import "@ada-cx/lovelace/style.css";

Both imports are required:

  • tokens.css defines the --lovelace-* custom properties inside @layer lovelace.tokens. It carries every design value: colors, fonts, spacing, radii.
  • style.css holds all component styles in one file. Those styles only reference the custom properties through var().

A JS-only import renders unstyled components. The library build extracts all component CSS to style.css, so importing components without the stylesheets produces bare, unthemed markup.

3. Wrap your UI in LovelaceProvider

LovelaceProvider is the prescribed entry point for consuming Lovelace.

1import { LovelaceProvider, Button } from "@ada-cx/lovelace";
2
3export function App() {
4  return (
5    <LovelaceProvider theme="auto">
6      <Button variant="primary">Send</Button>
7    </LovelaceProvider>
8  );
9}

The provider does three jobs:

  • It resolves the color scheme (light, dark, or auto) and stamps data-theme on its wrapper. auto follows the OS preference live.
  • It applies token overrides from its override prop.
  • It keeps React Aria overlay portals (Dialog, Sheet, Tooltip) inside the theme boundary.

Components render without the provider, and data-theme defaults to light. Without the provider you own theme switching and portal scoping yourself.

4. Verify the result

Run your dev server. You should see a filled accent button labeled “Send”. Hover and keyboard focus states style themselves through data-* attributes.

If the button renders as unstyled text, one or both stylesheet imports are missing. Check step 2.

Next steps