Astrology UI components, charts, kundli, and tarot

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

• npm: @roxyapi/ui, @roxyapi/ui-react, @roxyapi/ui-vue
• CDN: jsDelivr, no install needed
• No code: copy-paste widgets, a prefilled snippet per component for Squarespace, Wix, or any HTML block, powered by a publishable key
• shadcn registry: per-component install for Next.js + Tailwind projects
• Live preview: roxyapi.github.io/ui
• Source: github.com/RoxyAPI/ui, MIT licensed

Why RoxyAPI 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. ~85 KB gzipped for the full bundle (every domain), ~9-21 KB per component when imported individually.
• MIT licensed. Use it in commercial apps. No AGPL, no copyleft, no obligations.

Pick your path

Not a developer, or you just want a live reading on an existing site with zero code? Use Copy-paste widgets below. Building an app in a framework? Path A (most developers pick this). Path C is a Path A accelerator that drops a typed React wrapper into your repo per component.

Copy-paste widgets (no code)

The fastest way to put a live reading on a site you already have. A widget is the SAME component as the library below, run in a self-contained mode: paste one snippet, add a browser-safe publishable key, and the widget draws its own inputs (a birth-data form, a zodiac picker), fetches on submit, and renders the result. No SDK call to write, no server, no build step.

Every embeddable component has a prefilled snippet on the widgets gallery: paste your key there once and every snippet on the page fills itself in, so you copy ready-to-paste code for exactly the widget you want. Three ways to embed, same key.

https://roxyapi.com/embed/natal-chart?pk=pk_live_YOUR_KEY

<iframe src="https://roxyapi.com/embed/natal-chart?pk=pk_live_YOUR_KEY" title="Natal chart widget" style="border:0;width:100%;height:600px" loading="lazy"></iframe>

<script type="module" src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js"></script>
<div data-roxy-widget="natal-chart" data-publishable-key="pk_live_YOUR_KEY"></div>

<script type="module" src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>
<roxy-natal-chart data-endpoint="astrology/natal-chart" publishable-key="pk_live_YOUR_KEY"></roxy-natal-chart>

GET-based widgets (daily horoscope, moon phase) need method="GET" on the component tag; the one-tag data-roxy-widget form sets it for you. The widgets gallery always shows the exact snippet per widget. Platform walkthroughs: Squarespace, Wix, Shopify, and WordPress.

Path A: Next.js, Nuxt, and any other framework

1. Install

npm install @roxyapi/ui-react

Building with Vue or Nuxt instead:

npm install @roxyapi/ui-vue

@roxyapi/ui-react ships React 19 wrappers and @roxyapi/ui-vue ships Vue 3 wrappers. Both cover every component, take the same data prop, and load the underlying components from jsDelivr at mount time, so library updates ship to you without a re-install.

Any other framework (Svelte, Angular, Solid, Qwik, Astro) renders the elements natively: npm install @roxyapi/ui and use <roxy-vedic-kundli> directly. The wrapper packages exist for typed props and idiomatic imports, not because the components need them.

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.

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, type BirthChartResponse } from '@roxyapi/ui-react';

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

Every response type is exported from the component package, so you never declare your own interface and never install a second package just for types.

The Vue equivalent, for a Nuxt or Vite app. Fetch on the server exactly as above, then pass the response straight through:

<script setup lang="ts">
import { RoxyVedicKundli, type BirthChartResponse } from '@roxyapi/ui-vue';

defineProps<{ data: BirthChartResponse }>();
</script>

<template>
  <RoxyVedicKundli :data="data" />
</template>

In Nuxt, render these in a client context (<ClientOnly> or a .client.vue file): they mount custom elements and need the DOM, the same constraint as 'use client' in the Next.js App Router. You do not need compilerOptions.isCustomElement.

4. Run

npm run dev

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

Path B: Plain HTML (zero build step)

For a single page, an existing site, a WordPress shortcode, a Wix Embed HTML element, a Shopify theme, a Stan Store custom-code block, or a Linktree embed. This path fetches the data yourself and passes it to the component, so you control the exact request. If you would rather paste a ready-made widget that draws its own form and fetches for the visitor, use Copy-paste widgets above.

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

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

What you can render

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

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

Languages and localization

RoxyAPI components render in 8 languages: English, Turkish, German, Spanish, Hindi, Portuguese, French, and Russian. A component picks its language up from the page it is embedded in, so a site already published in Spanish or Hindi usually needs no configuration at all.

The language is chosen in this order, and the first answer wins:

1. A lang attribute on the component itself.
2. A lang attribute on any element wrapping it, so one wrapper can set a whole section.
3. The lang attribute on the page, which is what most site builders already emit (<html lang="es">).

That is why the copy-paste snippets on the widgets gallery and the component catalog carry no lang by default. Paste one onto a Spanish page and it renders in Spanish. Set lang yourself only when you want to fix the language regardless of the page, for example an English reading on an otherwise German site.

Load the labels for your language

Written readings arrive in your language automatically. The labels the component writes itself, such as headings, tab names, and table captions, live in a small separate file, one per language, so an English site downloads nothing extra. Add one line for the language you want:

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

Swap es for de, fr, hi, pt, ru, or tr. English needs no file. Order does not matter, and the file can arrive after the page has painted.

In a bundled app, import it instead:

import '@roxyapi/ui';
import '@roxyapi/ui/locales/es';

The widgets gallery and the component catalog both have a language selector next to the publishable-key field. Pick a language there and the snippet you copy already carries the right line.

Hosted embeds

The hosted embed URL takes lang on the query string and handles both halves for you, so nothing else is needed:

https://roxyapi.com/embed/natal-chart?pk=pk_live_YOUR_KEY&lang=es

An iframe is its own page, so it has nothing to inherit from. Without lang a hosted embed renders in English even on a Spanish site.

What is translated, and what is not

Being straight about this saves you a support ticket:

• Readings and interpretations follow the language on every endpoint. So do the planet, sign, aspect, and house names that come back with them.
• On-screen labels follow it on the charts that carry a translated label set today, which currently lead with the natal chart and the transit wheel. Coverage grows every release. Anything not yet covered renders its labels in English rather than breaking, so a page is never blank or half-rendered.
• Column headings on the plain data tables stay English. They are derived from the field names in the response, so a translated label set cannot reach them. The values inside those columns do follow the language.
• The visitor-facing form a widget draws for itself follows the language too, including its field labels and its dropdown options, so a Spanish page collects Fecha de nacimiento rather than Birth date. The explanatory help text under a field is still English while it is being translated, and a label a language has not covered yet falls back to English on its own rather than blocking the field.
• Fixing a language turns the page inheritance off. A component with an explicit lang ignores the page it sits on, which is the point, but it also means a later site-wide language change will not reach it.
• A regional tag works. es-AR uses the Spanish labels and Argentinian date and number formatting. A language RoxyAPI does not cover falls back to English rather than failing.

Theming

Every component reads from --roxy-* CSS custom properties. Custom properties cross the Shadow DOM boundary, so a value set on :root reaches every component below it. Override globally to match your brand:

:root {
  --roxy-bg: #fafafa;
  --roxy-fg: #0a0a0a;
  --roxy-muted: #71717a;
  --roxy-border: #e4e4e7;
  --roxy-accent: #f59e0b;
  --roxy-radius-md: 8px;
}

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

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

Those six are the ones most projects set. There are over a hundred more covering typography, spacing, radius, shadow, motion, and the status colors. The full reference, with the light and dark default for every token and what each one paints, is THEMING.md in the component repo. It is maintained alongside the components, so it never lags a release; the literal defaults are in tokens.css beside it. It also carries ready-made presets for dark mode, high contrast, per-domain accents, and a Tailwind token map.

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 RoxyAPI variables. Your shadcn theme drives RoxyAPI 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);
  }
}

Choosing what a component renders

Components are not all-or-nothing. Every structural block carries a part name, so you can restyle it, hide it from a stylesheet, or drop it from one placement with an attribute.

Target any block with ::part()

part names are the same in every component, so one rule covers the whole library. ::part(aspects) reaches the aspect grid on a natal chart and the aspect list on an aspects table alike.

/* Restyle one block. */
roxy-natal-chart::part(card) { border: 0; box-shadow: none }

/* Or remove it. */
roxy-natal-chart::part(patterns) { display: none }

Common names are card, header, chart, legend, details, table, readings, and patterns, plus form, loading, error, and attribution on the built-in states. Every structural section carries section plus its own name, so you can style all of them at once or one by one. To find the name for a block, open your browser inspector and read its part attribute.

hide-readings: keep the chart, drop the words

Set it when your own copy supplies the interpretation. The prose is left out of the markup entirely, so the page never ships text it is not showing.

<roxy-natal-chart hide-readings></roxy-natal-chart>

<RoxyNatalChart data={chart} hideReadings />

Wheels, maps, tables, grids, legends, badges, and every number stay. It is off by default.

hide-sections: remove a whole block

hide-readings draws its line on the content, not on the block, so a block made of measurements stays even when it reads like analysis. A natal chart pattern reports its figure, element, modality, tightness, and member planets, so it survives on purpose. To remove the block itself, name it:

<roxy-natal-chart hide-sections="patterns"></roxy-natal-chart>
<roxy-natal-chart hide-sections="patterns, legend"></roxy-natal-chart>

<RoxyNatalChart data={chart} hideSections="patterns" />

It takes a comma-separated list of part names and applies to every component, so a name it does not recognize is simply ignored rather than breaking the render. Use ::part() when one rule should cover a whole site, and hide-sections when two components on the same page need to differ.

On a hosted embed

Both work as query parameters, which is the only way to reach them through an iframe:

https://roxyapi.com/embed/natal-chart?pk=pk_live_YOUR_KEY&hide-sections=patterns
https://roxyapi.com/embed/natal-chart?pk=pk_live_YOUR_KEY&hide-readings=1

hide-readings is a switch, so any value turns it on. Leave the parameter off to keep the readings.

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

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

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

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

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