Installation

Get zostel-ui running in your React project in under five minutes.

Prerequisites

  • • Node.js 18+ and npm / pnpm / yarn
  • • React 19+ (peer dependency)
  • • Tailwind CSS v4 (uses the @theme directive)
1

Install the package

Install zostel-ui and its peer dependencies:

npm
npm install zostel-ui
pnpm
pnpm add zostel-ui
yarn
yarn add zostel-ui
2

Import the global stylesheet

The library ships a single globals.css that includes Tailwind v4, all brand tokens, animation keyframes, pattern backgrounds, and utility classes. Import it at the root of your application: 

// app/layout.tsx or main.tsx
import 'zostel-ui/styles/globals.css';

Note: This file contains @import "tailwindcss" at the top, so you do not need a separate Tailwind import. If you already have one, remove it to avoid duplication.

3

Tailwind CSS v4 configuration

Zostel UI is built for Tailwind CSS v4, which uses the new CSS-native configuration approach. No tailwind.config.js file is needed — all tokens are defined inside globals.css using the @theme directive.

Make sure your bundler (Vite, Next.js, or Astro) has the Tailwind v4 plugin installed: 

# Install Tailwind CSS v4
npm install tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

For Next.js, use the PostCSS plugin instead: 

# Install PostCSS plugin
npm install @tailwindcss/postcss

// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': ,
  },
};
4

Configure path aliases

For cleaner imports, set up a @zostel path alias in your tsconfig.json: 

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@zostel/*": ["./node_modules/zostel-ui/src/*"],
      "@/*": ["./src/*"]
    }
  }
}

Then import components with the alias: 

import { Button } from '@zostel/components/ui/button';
import { HostelCard } from '@zostel/components/travel/HostelCard';
import { useTheme } from '@zostel/lib/hooks/use-theme';
5

Verify the setup

Drop a quick test component into your app to confirm everything is wired up: 

import { Button } from '@zostel/components/ui/button';

export default function TestPage() {
  return (
    <div className="p-8 bg-background min-h-screen">
      <h1 className="text-2xl font-bold text-foreground mb-4">
        Zostel UI is working!
      </h1>
      <Button>Book a Bed</Button>
      <Button variant="outline" className="ml-2">Explore</Button>
    </div>
  );
}

If you see the Zostel-orange primary button and the beige background, you are good to go.

Next Steps

Theming

Learn how to customise colours, fonts, and dark mode.

Button

Start building with the most common component.
Previous Introduction Next Theming