Quick start

Build your first app

This guide will walk you through creating a simple application using Apsara components. You’ll learn how to use layouts, buttons, and theme customization.

Make sure you’ve installed Apsara before starting this guide.

Import the required components

Start by importing the components and styles you’ll need:

App.tsx

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

The style.css import provides all the base styles for Apsara components.

Create a layout with Flex

Use the Flex component to create a flexible layout container:

App.tsx

function App() {
  return (
    <Flex
      direction="column"
      align="center"
      justify="center"
      gap="large"
    >
      <h1>Welcome to Apsara</h1>
    </Flex>
  );
}

The Flex component provides props for controlling flexbox layout:

direction: row, column, rowReverse, columnReverse
align: start, center, end, stretch, baseline
justify: start, center, end, between
gap: 1-9, extra-small, small, medium, large, extra-large

Add buttons with variants

Add buttons with different variants to your layout:

App.tsx

function App() {
  return (
    <Flex
      direction="column"
      align="center"
      justify="center"
      gap="large"
    >
      <h1>Welcome to Apsara</h1>
      
      <Flex gap="medium">
        <Button variant="solid" color="accent">
          Primary Action
        </Button>
        <Button variant="outline" color="neutral">
          Secondary
        </Button>
        <Button variant="ghost" color="danger">
          Delete
        </Button>
      </Flex>
    </Flex>
  );
}

Buttons support multiple variants and colors:

Variants: solid, outline, ghost, text
Colors: accent, neutral, danger, success
Sizes: small, normal

Add loading states and icons

Buttons can show loading states and include icons:

App.tsx

import { Button, Flex } from "@raystack/apsara";
import { PlusIcon } from "@raystack/apsara/icons";

function App() {
  const [loading, setLoading] = useState(false);

  const handleClick = () => {
    setLoading(true);
    setTimeout(() => setLoading(false), 2000);
  };

  return (
    <Flex gap="medium">
      <Button
        variant="solid"
        color="accent"
        loading={loading}
        loaderText="Saving..."
        onClick={handleClick}
      >
        Save Changes
      </Button>
      
      <Button
        variant="outline"
        leadingIcon={<PlusIcon />}
      >
        Add Item
      </Button>
    </Flex>
  );
}

Use loaderText to show text while loading, or omit it to show only the spinner.

Set up theme provider

Wrap your application with ThemeProvider to enable theming and dark mode:

App.tsx

import { ThemeProvider, ThemeSwitcher } from "@raystack/apsara";

function App() {
  return (
    <ThemeProvider
      defaultTheme="light"
      style="modern"
      accentColor="indigo"
      grayColor="gray"
    >
      <Flex direction="column" gap="large">
        <Flex justify="end">
          <ThemeSwitcher />
        </Flex>
        
        <Flex direction="column" align="center" gap="large">
          <h1>Welcome to Apsara</h1>
          
          <Flex gap="medium">
            <Button variant="solid" color="accent">
              Get Started
            </Button>
            <Button variant="outline" color="neutral">
              Learn More
            </Button>
          </Flex>
        </Flex>
      </Flex>
    </ThemeProvider>
  );
}

The ThemeProvider accepts several props:

defaultTheme: “light”, “dark”, or “system”
style: Theme style variant
accentColor: Primary accent color
grayColor: Gray scale variant
enableSystem: Enable system theme detection (default: true)

Complete example

Here’s a complete working example that combines everything:

App.tsx

import { useState } from "react";
import "@raystack/apsara/style.css";
import {
  Button,
  Flex,
  ThemeProvider,
  ThemeSwitcher,
  InputField,
} from "@raystack/apsara";

function App() {
  const [email, setEmail] = useState("");
  const [loading, setLoading] = useState(false);

  const handleSubmit = () => {
    setLoading(true);
    // Simulate API call
    setTimeout(() => {
      console.log("Email submitted:", email);
      setLoading(false);
    }, 2000);
  };

  return (
    <ThemeProvider defaultTheme="system" accentColor="indigo">
      <div style={{ minHeight: "100vh", padding: "2rem" }}>
        <Flex direction="column" gap="large">
          {/* Header with theme switcher */}
          <Flex justify="between" align="center">
            <h1>My Apsara App</h1>
            <ThemeSwitcher />
          </Flex>

          {/* Main content */}
          <Flex direction="column" align="center" gap="large">
            <div style={{ maxWidth: "400px", width: "100%" }}>
              <Flex direction="column" gap="medium">
                <InputField
                  type="email"
                  placeholder="Enter your email"
                  value={email}
                  onChange={(e) => setEmail(e.target.value)}
                />
                
                <Flex gap="medium">
                  <Button
                    variant="solid"
                    color="accent"
                    loading={loading}
                    loaderText="Submitting..."
                    onClick={handleSubmit}
                    disabled={!email}
                  >
                    Submit
                  </Button>
                  <Button
                    variant="outline"
                    color="neutral"
                    onClick={() => setEmail("")}
                  >
                    Clear
                  </Button>
                </Flex>
              </Flex>
            </div>
          </Flex>
        </Flex>
      </div>
    </ThemeProvider>
  );
}

export default App;

Using the useTheme hook

Access and control the theme programmatically using the useTheme hook:

import { useTheme } from "@raystack/apsara";

function MyComponent() {
  const { theme, setTheme, resolvedTheme } = useTheme();

  return (
    <div>
      <p>Current theme: {theme}</p>
      <p>Resolved theme: {resolvedTheme}</p>
      
      <Button onClick={() => setTheme("dark")}>
        Switch to Dark
      </Button>
      <Button onClick={() => setTheme("light")}>
        Switch to Light
      </Button>
      <Button onClick={() => setTheme("system")}>
        Use System
      </Button>
    </div>
  );
}

The useTheme hook returns:

theme: Current theme setting (“light”, “dark”, or “system”)
setTheme: Function to change the theme
resolvedTheme: Actual theme being used (resolves “system” to “light” or “dark”)
systemTheme: The system’s preferred theme
themes: Array of available themes

Use resolvedTheme when you need to know the actual theme being displayed, especially when using “system” mode.

Layout patterns

Here are some common layout patterns using the Flex component:

<Flex direction="row" gap="medium" align="center">
  <Button>First</Button>
  <Button>Second</Button>
  <Button>Third</Button>
</Flex>

<Flex direction="column" gap="large">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Flex>

<Flex justify="between" align="center">
  <div>Left content</div>
  <div>Right content</div>
</Flex>

<Flex
  direction="column"
  align="center"
  justify="center"
  style={{ minHeight: "100vh" }}
>
  <h1>Centered Content</h1>
</Flex>

Next steps

Now that you’ve built your first app with Apsara, explore more features:

Components

Explore all 55+ available components

Theming

Learn how to customize colors and styles

Dark mode

Implement dark mode in your app

Accessibility

Learn about accessibility features

All Apsara components are accessible by default and follow ARIA best practices.

Get Started

Guides

Layout Components

Navigation Components

Data Display

Form Components

Feedback Components

Overlay Components

Utility Components

Build your first app

Complete example

Using the useTheme hook

Layout patterns

Next steps

Components

Theming

Dark mode

Accessibility

​Build your first app

​Complete example

​Using the useTheme hook

​Layout patterns

​Next steps

Components

Theming

Dark mode

Accessibility

Build your first app

Complete example

Using the useTheme hook

Layout patterns

Next steps