Getting Started

This guide walks you through installing Apsara and building your first component.

Prerequisites

Apsara requires:

Node.js 18 or later
React 18 or 19

Installation

Install the package using your preferred package manager:

1npm install @raystack/apsara

Setup

1. Import styles

Add the CSS import at the root of your application, before any component renders:

1import "@raystack/apsara/style.css";

This single stylesheet includes all component styles and CSS custom properties (tokens) for theming.

2. Add ThemeProvider

Wrap your application with ThemeProvider to enable theming support:

1import { ThemeProvider } from "@raystack/apsara";
2import "@raystack/apsara/style.css";
3
4function App() {
5  return (
6    <ThemeProvider defaultTheme="system">
7      <YourApp />
8    </ThemeProvider>
9  );
10}

The defaultTheme prop accepts "light", "dark", or "system" (follows OS preference).

3. Use components

Import and use components directly:

1import { Button, Flex, Text } from "@raystack/apsara";
2
3function Example() {
4  return (
5    <Flex direction="column" gap="4">
6      <Text size="4" weight="medium">Welcome to Apsara</Text>
7      <Flex gap="3">
8        <Button variant="solid" color="accent">Primary Action</Button>
9        <Button variant="outline">Secondary</Button>
10      </Flex>
11    </Flex>
12  );
13}

Framework Setup

Next.js (App Router)

Add the provider to your root layout:

1// app/layout.tsx
2import { ThemeProvider } from "@raystack/apsara";
3import "@raystack/apsara/style.css";
4
5export default function RootLayout({ children }: { children: React.ReactNode }) {
6  return (
7    <html lang="en" suppressHydrationWarning>
8      <body>
9        <ThemeProvider defaultTheme="system">
10          {children}
11        </ThemeProvider>
12      </body>
13    </html>
14  );
15}

The suppressHydrationWarning attribute is required because ThemeProvider injects a script to prevent theme flash during hydration.

Vite

Add the provider to your main entry file:

1// main.tsx
2import React from "react";
3import ReactDOM from "react-dom/client";
4import { ThemeProvider } from "@raystack/apsara";
5import "@raystack/apsara/style.css";
6import App from "./App";
7
8ReactDOM.createRoot(document.getElementById("root")!).render(
9  <React.StrictMode>
10    <ThemeProvider defaultTheme="system">
11      <App />
12    </ThemeProvider>
13  </React.StrictMode>
14);

Optional: Normalize CSS

Apsara includes an optional normalize stylesheet that ensures consistent rendering across browsers while preserving useful defaults:

1import "@raystack/apsara/normalize.css";
2import "@raystack/apsara/style.css";

Import it before the main stylesheet if you choose to use it.

Importing Icons

Apsara exports a set of icons that can be imported separately:

1import { MagnifyingGlassIcon, Cross2Icon } from "@raystack/apsara/icons";
2
3<Button leadingIcon={<MagnifyingGlassIcon />}>Search</Button>

Importing Hooks

Utility hooks are available from a dedicated export:

1import { useTheme } from "@raystack/apsara/hooks";
2
3function ThemeToggle() {
4  const { resolvedTheme, setTheme } = useTheme();
5
6  return (
7    <Button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
8      Toggle Theme
9    </Button>
10  );
11}

Next Steps

Theme Overview — Configure colors, spacing, and style variants
Button — Start with a common component
DataTable — Build data-rich interfaces