UI Components

Open source web components for every RoxyAPI domain. Drop in a natal chart, kundli wheel, panchang table, dasha timeline, tarot spread, biorhythm chart, hexagram, numerology card, or location search. Ship a finished astrology, tarot, or numerology app without writing a single line of SVG, table layout, or form code.

npm: @roxyapi/ui, @roxyapi/ui-react
CDN: jsDelivr, no install needed
shadcn registry: per-component install for Next.js + Tailwind projects
Live preview: roxyapi.github.io/ui
Source: github.com/RoxyAPI/ui, MIT licensed

Why Roxy UI

Most data APIs leave you to build the visual layer yourself. Birth charts mean SVG geometry, panchang means complex tables, dasha means timelines, tarot means card layouts and reversed-card flips. We ship the finished components so you keep your time for product work.

Stateless. You fetch with the SDK, pass the response as the data prop, the component renders. No internal fetches, no auth, no global stores.
Framework agnostic. React, Next.js, Vue, Svelte, Angular, Solid, vanilla HTML, WordPress. Same components everywhere.
CSS custom properties for theming. Override 30+ tokens for color, spacing, radius, motion. Match any brand without rebuilding the bundle.
Accessible by default. WAI-ARIA roles, keyboard navigation, reduced-motion gating, axe-core verified.
Tiny. ~26 KB gzipped for the full bundle, ~8-10 KB per component when imported individually.
MIT licensed. Use it in commercial apps. No AGPL, no copyleft, no obligations.

Designed for the developer who is great at backend or business logic but does not want to spend a week on chart geometry, the founder who does not want to hire a UI designer for a weekend project, and the AI agent that needs to render a structured astrology response without inventing markup.

Pick your path

You are building	Use this path	Time to first chart
Next.js, Remix, Nuxt, SvelteKit, Astro, Vue, Svelte, Angular, Solid, Qwik	Path A: npm + framework wrapper	~5 min
Plain HTML, WordPress, Shopify theme, Stan Store, Linktree, Notion embed	Path B: jsDelivr CDN, no build step	~30 seconds
Next.js + Tailwind + shadcn already set up	Path C: shadcn registry	~5 min

Most developers pick A or B. Path C is a Path A accelerator that drops a typed React wrapper into your repo per component.

Path A: Next.js (and any other framework with React)

1. Install

npm install @roxyapi/ui-react @roxyapi/sdk

@roxyapi/ui-react ships React 19 wrappers. The underlying components load from jsDelivr at mount time so library updates ship to you without a re-install.

2. Set your API key

In .env.local at the project root:

ROXY_API_KEY=your_api_key_here

Get a key at roxyapi.com/account. Server-side use only.

Never expose a secret API key in client-side code. Call Roxy from a server route, server action, or edge function. Anything in NEXT_PUBLIC_* ships to the browser and can be scraped.

3. Fetch on the server, render on the client

This is the recommended Next.js App Router pattern. The Server Component fetches with your secret key, the Client Component renders the wheel.

app/page.tsx:

import { createRoxy } from '@roxyapi/sdk';
import BirthChartView from './birth-chart-view';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

export default async function Page() {
  const { data } = await roxy.vedicAstrology.generateBirthChart({
    body: {
      date: '1990-01-15',
      time: '14:30:00',
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 5.5,
    },
  });

  return (
    <main>
      <h1>My astrology app</h1>
      <BirthChartView data={data} />
    </main>
  );
}

app/birth-chart-view.tsx:

'use client';

import { RoxyVedicKundli } from '@roxyapi/ui-react';

export default function BirthChartView({ data }: { data: unknown }) {
  return <RoxyVedicKundli data={data} />;
}

4. Run

npm run dev

Open http://localhost:3000. The kundli renders.

First render shows a brief blank state while the component code loads from the CDN (~26 KB gzipped). Render a skeleton or fallback while data is undefined for a polished feel.

Path B: Plain HTML (zero build step)

For a single page, an existing site, a WordPress shortcode, a Shopify theme, a Stan Store custom-code block, or a Linktree embed.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My astrology page</title>
  <script
    src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"
    crossorigin="anonymous"
    defer
  ></script>
</head>
<body>
  <roxy-vedic-kundli id="kundli"></roxy-vedic-kundli>

  <script type="module">
    import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
    const roxy = createRoxy('YOUR_PUBLISHABLE_KEY');
    const { data } = await roxy.vedicAstrology.generateBirthChart({
      body: {
        date: '1990-01-15',
        time: '14:30:00',
        latitude: 28.6139,
        longitude: 77.209,
        timezone: 5.5,
      },
    });
    document.getElementById('kundli').data = data;
  </script>
</body>
</html>

Open the file in any browser. The kundli renders. Same pattern works in WordPress shortcodes, Shopify themes, Stan Store, Linktree, Notion, Bubble, Wix, Squarespace, or any builder that accepts custom HTML.

For browser-side calls, use a publishable key (pk_live_* / pk_test_*), not a secret key. Publishable keys are origin-restricted at the API gateway, so a leaked key from another domain returns 403 instead of burning your quota. Get one at roxyapi.com/account and register the domains you embed on.

Pin the version in production

Marketing snippets use @latest. Production code should pin to a concrete version so a CDN update never surprises you.

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0/dist/cdn/roxy-ui.js"></script>

Path C: shadcn registry (Next.js + Tailwind)

Already running shadcn? Install per-component. Each entry drops a typed React wrapper into components/roxy-ui/{name}.tsx and merges the CSS variable theme bridge into your globals.css so your existing shadcn theme drives Roxy components automatically.

npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/vedic-kundli.json

Use the wrapper:

import { RoxyVedicKundli } from '@/components/roxy-ui/vedic-kundli';

export default async function Page() {
  const data = await fetchKundliFromYourServer();
  return <RoxyVedicKundli data={data} />;
}

The wrapper file is a starter you own. Open it and customize freely.

Roxy components install under components/roxy-ui/, not components/ui/. Your shadcn button.tsx, card.tsx, input.tsx stay untouched.

What you can render

Every component takes a typed response from the matching endpoint. Pass the SDK response, the component figures out the rest.

Component	Domain	What it renders
`<roxy-natal-chart>`	Western astrology	Natal chart wheel with planet glyphs and aspect lines
`<roxy-horoscope-card>`	Western astrology	Daily, weekly, or monthly horoscope card
`<roxy-synastry-chart>`	Western astrology	Dual-wheel synastry plus inter-aspects table
`<roxy-moon-phase>`	Western astrology	Moon phase card and calendar grid
`<roxy-vedic-kundli>`	Vedic astrology	South or North Indian kundli layout
`<roxy-panchang-table>`	Vedic astrology	Tithi, vara, nakshatra, yoga, karana, plus muhurtas
`<roxy-dasha-timeline>`	Vedic astrology	Vimshottari mahadasha plus antardasha plus pratyantardasha
`<roxy-dosha-card>`	Vedic astrology	Manglik, Kalsarpa, Sade Sati severity, exceptions, remedies
`<roxy-guna-milan>`	Vedic astrology	36-point Ashtakoota with eight Koot sub-scores
`<roxy-kp-planets-table>`	Vedic (KP system)	KP planets with sub-lord and sub-sub-lord columns
`<roxy-numerology-card>`	Numerology	Life Path, Expression, Personal Year, full chart
`<roxy-tarot-card>`	Tarot	Single card with upright and reversed flip
`<roxy-tarot-spread>`	Tarot	Three-card, Celtic Cross, love, career spreads
`<roxy-biorhythm-chart>`	Biorhythm	Daily bars, multi-day forecast, critical days
`<roxy-hexagram>`	I Ching	Hexagram with trigrams, judgment, image, changing lines
`<roxy-compatibility-card>`	Cross-domain	Score card with category breakdown
`<roxy-location-search>`	Helper	Debounced city search, fires `roxy-location-select` event
`<roxy-endpoint-form>`	Helper	Schema-driven form for any endpoint

Full live preview of every component at roxyapi.github.io/ui. Click any component for a Preview tab and a copy-paste Code tab.

Theming

Every component reads from CSS custom properties on :root. Override globally to match your brand.

:root {
  --roxy-bg: #fafafa;
  --roxy-fg: #0a0a0a;
  --roxy-muted: #71717a;
  --roxy-border: #e4e4e7;

  --roxy-accent: #f59e0b;
  --roxy-accent-fg: #b45309;

  --roxy-radius-md: 12px;
  --roxy-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
  --roxy-motion-duration: 200ms;
}

[data-theme="dark"] {
  --roxy-bg: #0a0a0a;
  --roxy-fg: #fafafa;
  --roxy-muted: #a1a1aa;
  --roxy-border: #27272a;
}

Or override per element to deviate one component without touching the rest:

roxy-natal-chart {
  --roxy-accent: #ec4899;
  --roxy-radius-md: 8px;
}

The live preview at roxyapi.github.io/ui has a Customize button (top right) that visualizes every token and outputs a CSS block you paste into your project.

Already on shadcn?

Path C installs a thin bridge that maps your existing shadcn --background, --foreground, --primary, --border, --radius onto the Roxy variables. Your shadcn theme drives Roxy components automatically. Path A and Path B users can ship the same bridge as a small CSS file:

@layer base {
  :root {
    --roxy-bg: var(--background, #fafafa);
    --roxy-fg: var(--foreground, #0a0a0a);
    --roxy-accent: var(--primary, #f59e0b);
    --roxy-border: var(--border, #e4e4e7);
    --roxy-radius-md: var(--radius, 12px);
  }
}

Wiring custom events

Some components dispatch typed events: roxy-submit, roxy-location-select, roxy-validation-error. The React wrappers expose them as handler props.

import { RoxyLocationSearch } from '@roxyapi/ui-react';

<RoxyLocationSearch
  onRoxyLocationSelect={(e) => {
    console.log(e.detail.latitude, e.detail.longitude, e.detail.timezone);
  }}
/>

In vanilla HTML, listen the standard way:

<roxy-location-search id="search"></roxy-location-search>
<script>
  document.getElementById('search').addEventListener('roxy-location-select', (e) => {
    console.log(e.detail.latitude, e.detail.longitude, e.detail.timezone);
  });
</script>

Common gotchas

`[object Object]` in the rendered chart

You passed the SDK envelope instead of the unwrapped response.

Wrong:

const response = await roxy.vedicAstrology.generateBirthChart({...});
element.data = response;

Right:

const { data } = await roxy.vedicAstrology.generateBirthChart({...});
element.data = data;

The SDK returns { data, error, request, response }. Always destructure data.

"Loading..." that never resolves

The API call is failing silently. Open the network tab and check the status code.

401 api_key_required: pass your key to createRoxy(...).
401 invalid_api_key: typo in the key.
403 origin_not_allowed: publishable key called from an origin not in its allowlist. Add the origin at roxyapi.com/account.
429 rate_limit_exceeded: monthly quota burned. Quota resets on the 1st.

`'use client'` errors in Next.js App Router

The wrappers use the DOM. Add 'use client' at the top of any file that imports from @roxyapi/ui-react. Server Components cannot import them directly. The recommended pattern is "fetch in a Server Component, render in a small Client Component" (see Path A).

Empty page on first paint

Expected. The wrapper loads the component code from the CDN (~26 KB gzipped) on mount. Render a fallback while data is null, or preload the bundle in your <head>:

<link
  rel="preload"
  as="script"
  crossOrigin="anonymous"
  href="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"
/>

Components work locally but break on GitHub Pages or any sub-path host

You used origin-absolute paths (/something). Use relative paths (./something) or set <base href="./">.

Tarot card images return CORS errors

The component reads imageUrl from the response. Either serve those images from your own CDN, or set Cross-Origin-Resource-Policy: cross-origin on your image host.

React 17 or 18 ignores hyphenated event names

Upgrade to React 19 if you can. If you cannot, bind manually with addEventListener in useEffect instead of using the onRoxy* props.

Verification checklist

After integrating, confirm:

No [object Object] strings in any chart, table, or card.
No "Loading..." that never resolves.
Browser console has no errors and no warnings.
Dark mode flips when you toggle [data-theme="dark"] on <html>.
Production build (npm run build) compiles without errors.
The key in any client-bundled code is a publishable key, not a secret one.

Where to go next

Live customizer at roxyapi.github.io/ui. Theme tokens, copy-paste integration snippets, every component rendered against real responses.
Source code at github.com/RoxyAPI/ui. MIT licensed. Issues, contributions, and release notes welcome.
Catalog page at roxyapi.com/ui for distribution surfaces and FAQ.
SDK reference at /docs/sdk for every endpoint method.
Get an API key at roxyapi.com/pricing. Instant delivery, no approval queue.

Frequently asked questions

Is Roxy UI really free?

Yes. MIT licensed. Use it in commercial apps.

Can I use it without the SDK?

Yes. Components are stateless. Fetch with fetch, axios, your favorite client, your own server proxy, anything. Pass the response as the data prop.

Does it support React Native or Flutter?

Not yet. Web (browsers and webviews) only as of 2026.

Will my brand colors work?

Yes. Override the --roxy-* CSS custom properties on :root or per element. The live preview has a Customize button that exports a CSS block.

Do I need a separate UI/UX designer?

No. The components ship with sensible defaults out of the box. Theme to your brand colors and you are done.

Can AI coding agents use this?

Yes. Cursor, Claude Code, GitHub Copilot, Codex, and any agent reading your package.json will see @roxyapi/ui and the standard component names. Path C drops typed wrapper files into your repo, which makes agent navigation even easier.

How big is the bundle?

~26 KB gzipped for the full bundle from the CDN. ~8-10 KB per component when imported individually via the framework wrappers.

Is there a TypeScript type for the response shape?

Yes. The SDK ships full types. The component data prop is typed against the matching endpoint response. Your IDE catches schema drift before runtime.

What if my endpoint is not in the component list?

The catch-all <roxy-data> element renders any response shape as a structured table. New endpoints work out of the box; bespoke components ship as the catalog grows.