Getting started: Astro

React islands (client:load) with SSR; static markup with the package's classes works with no JS at all

1. Create the app and add React

npm create astro@latest my-app -- --template minimal
cd my-app
npx astro add react

2. Install the package

Works with react and react-dom 17, 18 and 19 (React 17: ids from useId appear right after mount). The package ships ES modules (plus a CommonJS copy for require()), has no runtime dependencies and has one file per module, so your bundle includes only the components you import; to load only their CSS as well, see “Only the CSS you need” below. Fonts are separate files: the vercel theme (the ThemeProvider default) uses Geist, so import valyro-ui/fonts/geist.css and valyro-ui/fonts/geist-mono.css next to the styles, or text falls back to the system font; glass uses system fonts and needs none. Until the package is published, build and pack it in the repository (npm run build:core && npm pack ./dist/core) and install the tarball from the repository root: npm install /path/to/ValyroUI/valyro-ui-0.1.0.tgz.

npm install valyro-ui

3. ThemeProvider in every island

Each island is a separate React root, so wrap its content in ThemeProvider (charts and some components read the theme from context). The toast store is shared by all islands on the page.

import { ThemeProvider } from 'valyro-ui';
import { Showcase } from './Showcase';

// Every Astro island is its own React root, so each one gets a ThemeProvider.
export default function ShowcaseIsland() {
  return (
    <ThemeProvider theme="glass" mode="light" locale="en-US">
      <Showcase />
    </ThemeProvider>
  );
}

4. Page

Import the styles in the frontmatter and put the theme attributes on <html>. Without a client:* directive, a component renders to HTML with no JS. Showcase comes from the Next.js guide (you can drop the 'use client' line).

---
import 'valyro-ui/styles.css';
import ShowcaseIsland from '../components/ShowcaseIsland';
---

<html lang="en" data-theme="glass" data-mode="light">
	<head>
		<meta charset="utf-8" />
		<meta name="viewport" content="width=device-width" />
		<title>ValyroUI on Astro</title>
	</head>
	<body>
		<!-- Static markup: plain HTML + ValyroUI classes, no JavaScript shipped. -->
		<button class="ui-button" data-variant="secondary" data-size="md" type="button">
			<span class="ui-button__label">Static button</span>
		</button>
		<ShowcaseIsland client:load />
	</body>
</html>

5. Build

npm run build
npm run preview

Other frameworks