Skip to main content

​
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

​
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).
1

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

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";

​
Basic setup example

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

Install the package

npm install @raystack/apsara
2

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;
3

Start using components

Import and use any Apsara component in your application:
import { Button, InputField, Select } from "@raystack/apsara";

​
Framework-specific setup

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.
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>
);
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