Installation

Prerequisites

Before installing Apsara, make sure you have:

Node.js 22 or higher installed on your system
A React project with React 18 or 19
Package manager: npm, yarn, or pnpm

Apsara requires React 18+ and Node.js 22+ to work properly.

Install the package

Install Apsara using your preferred package manager:

npm install @raystack/apsara

yarn add @raystack/apsara

pnpm add @raystack/apsara

Import styles

Apsara uses vanilla CSS for styling. You need to import the CSS file in your application root (e.g., main.tsx, App.tsx, or _app.tsx).

Import the CSS file

Add the following import at the top of your root file:

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

The CSS import should be done once at the root of your application.

Optional: Import normalize CSS

For consistent cross-browser styling, you can also import the normalize CSS:

import "@raystack/apsara/normalize.css";

TypeScript setup

Apsara is written in TypeScript and includes comprehensive type definitions. No additional setup is required - types are automatically included when you install the package.

import { Button, Flex } from "@raystack/apsara";
import type { ButtonProps } from "@raystack/apsara";

// TypeScript will automatically infer types
const MyComponent = () => {
  return (
    <Flex gap="medium">
      <Button variant="solid" color="accent">
        Click me
      </Button>
    </Flex>
  );
};

The @types/react peer dependency is optional. TypeScript will work with or without it.

Package exports

Apsara provides several entry points for different use cases:

// Import components from the main entry
import { Button, Flex, Input } from "@raystack/apsara";

// Import icons separately
import { IconName } from "@raystack/apsara/icons";

// Import hooks separately
import { useCopyToClipboard, useTheme } from "@raystack/apsara/hooks";

/* Import CSS files */
@import "@raystack/apsara/style.css";
@import "@raystack/apsara/normalize.css";

Basic setup example

Here’s a complete example of setting up Apsara in a React application:

Install the package

npm install @raystack/apsara

Import styles in your root file

App.tsx

import "@raystack/apsara/style.css";
import { Button, Flex } from "@raystack/apsara";

function App() {
  return (
    <div className="app">
      <h1>My Apsara App</h1>
      <Flex gap="medium">
        <Button variant="solid">Get Started</Button>
      </Flex>
    </div>
  );
}

export default App;

Start using components

Import and use any Apsara component in your application:

import { Button, InputField, Select } from "@raystack/apsara";

Framework-specific setup

Next.js

For Next.js applications, import the CSS in your root layout or _app.tsx:

app/layout.tsx

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

If using the Pages Router, import in pages/_app.tsx instead.

Vite

For Vite applications, import the CSS in your main.tsx:

main.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import "@raystack/apsara/style.css";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Create React App

For Create React App, import the CSS in your index.tsx or App.tsx:

index.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import "@raystack/apsara/style.css";
import App from "./App";

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Peer dependencies

Apsara has the following peer dependencies:

react: ^18 || ^19
react-dom: ^18 || ^19
@types/react: ^18 || ^19 (optional)

Make sure your project meets these peer dependency requirements to avoid compatibility issues.

Next steps

Now that you have Apsara installed, you’re ready to start building!

Quick start

Follow the quick start guide to build your first component

Theming

Learn how to customize the look and feel

Components

Browse the complete component library

Dark mode

Set up dark mode in your application

Get Started

Guides

Layout Components

Navigation Components

Data Display

Form Components

Feedback Components

Overlay Components

Utility Components

Prerequisites

Install the package

Import styles

TypeScript setup

Package exports

Basic setup example

Framework-specific setup

Peer dependencies

Next steps

Quick start

Theming

Components

Dark mode

​Prerequisites

​Install the package

​Import styles

​TypeScript setup

​Package exports

​Basic setup example

​Framework-specific setup

​Peer dependencies

​Next steps

Quick start

Theming

Components

Dark mode

Prerequisites

Install the package

Import styles

TypeScript setup

Package exports

Basic setup example

Framework-specific setup

Peer dependencies

Next steps