Installation

Install packages

npm install @ghostly-ui/core @ghostly-ui/react

yarn add @ghostly-ui/core @ghostly-ui/react

pnpm add @ghostly-ui/core @ghostly-ui/react

bun add @ghostly-ui/core @ghostly-ui/react

Setup

Import the CSS

Add the Ghostly stylesheet to your global CSS file:

globals.css

@import '@ghostly-ui/core/css';

Or import it directly in your root layout:

app/layout.tsx

import '@ghostly-ui/core/css'

Wrap your components

page.tsx

import { Ghostly } from '@ghostly-ui/react'

function UserPage() {
  const { data, isLoading } = useFetch('/api/user')

  return (
    <Ghostly loading={isLoading} smooth>
      <UserProfile user={data} />
    </Ghostly>
  )
}

Or use GhostlySuspense for automatic skeleton with Suspense:

page.tsx

import { GhostlySuspense } from '@ghostly-ui/react'

function UserPage() {
  return (
    <GhostlySuspense fallback={<UserProfile />}>
      <AsyncUserProfile />
    </GhostlySuspense>
  )
}

That's it

No CLI. No build step. No config files. No code changes to your components.

Requirements

React >= 18.0.0
CSS imports — Any bundler that supports CSS imports (Next.js, Vite, Webpack, etc.)

Optional: Global configuration

Set default animation, radius, and speed for all Ghostly instances:

app/layout.tsx

import { GhostlyProvider } from '@ghostly-ui/react'
import '@ghostly-ui/core/css'

export default function RootLayout({ children }) {
  return (
    <GhostlyProvider animation="shimmer" radius="md" speed="normal">
      {children}
    </GhostlyProvider>
  )
}

Nested GhostlyProvider components inherit values from their parent. Only specify the values you want to override.

Optional: Tailwind CSS plugin

If your project uses Tailwind CSS, add the Ghostly plugin for utility classes:

tailwind.config.js

import ghostly from '@ghostly-ui/core/tailwind'

export default {
  plugins: [ghostly],
}

This gives you utilities like ghostly-radius-lg, ghostly-speed-fast, ghostly-color-[...], and the ghostly: variant.

Components handle undefined props with optional chaining (data?.title). This is standard React best practice and makes components work with Ghostly, Suspense, and loading states.

On this page