# 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`](https://www.npmjs.com/package/@roxyapi/ui), [`@roxyapi/ui-react`](https://www.npmjs.com/package/@roxyapi/ui-react), [`@roxyapi/ui-vue`](https://www.npmjs.com/package/@roxyapi/ui-vue)
- **CDN**: [jsDelivr](https://www.jsdelivr.com/package/npm/@roxyapi/ui), no install needed
- **No code**: [copy-paste widgets](/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](https://roxyapi.github.io/ui/)
- **Source**: [github.com/RoxyAPI/ui](https://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.
**Tip: 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 live |
|---|---|---|
| A site you already have (Squarespace, Wix, Shopify, WordPress, Notion, Linktree) and you just want a ready-made widget that draws its own form and fetches for the visitor | **Copy-paste widgets**: one snippet, no code | ~2 min |
| Next.js, Remix, Nuxt, SvelteKit, Astro, Vue, Svelte, Angular, Solid, Qwik | **Path A**: npm + framework wrapper | ~5 min |
| Plain HTML where you fetch the data yourself and pass it in | **Path B**: jsDelivr CDN, no build step | ~30 seconds |
| Next.js + Tailwind + shadcn already set up | **Path C**: shadcn registry | ~5 min |
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](/widgets)**: 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.
### Hosted embed URL
Paste this as a link into any block that accepts one: a Notion embed, a Linktree link, a Stan Store block, or a Squarespace embed block. RoxyAPI hosts the page, you host nothing.
```
https://roxyapi.com/embed/natal-chart?pk=pk_live_YOUR_KEY
```
### Iframe
Paste into any HTML block. Works where a raw script tag is not allowed.
```html
```
### Script tag
Load the widgets script once, then drop one `div` per widget. The `data-roxy-widget` slug picks the widget, and it renders its own form and fetches for the visitor.
```html
```
Want the full component bundle and per-tag control instead? Load `roxy-ui.js` and place the component tag with its endpoint:
```html
```
**Warning: Use a publishable key and allowlist your site**
Widgets run in the browser, so they take a publishable key (`pk_live_*` or `pk_test_*`), never a secret `sk_` key (the widget refuses one client-side). Create one at [roxyapi.com/account](/account?tab=keys) and add your site host to its origin allowlist. The same key works on all three delivery modes above, and a copied key cannot spend your quota from another domain.
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](/widgets) always shows the exact snippet per widget. Platform walkthroughs: [Squarespace](/docs/integrations/squarespace), [Wix](/docs/integrations/wix), [Shopify](/docs/integrations/shopify), and [WordPress](/docs/integrations/wordpress).
## Path A: Next.js, Nuxt, and any other framework
### 1. Install
```bash
npm install @roxyapi/ui-react
```
Building with Vue or Nuxt instead:
```bash
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 `` 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](/account). Server-side use only.
**Warning: Never expose a secret API key in client-side code. Call RoxyAPI 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`:
```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 (
My astrology app
);
}
```
`app/birth-chart-view.tsx`:
```tsx
'use client';
import { RoxyVedicKundli, type BirthChartResponse } from '@roxyapi/ui-react';
export default function BirthChartView({ data }: { data: BirthChartResponse }) {
return ;
}
```
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:
```vue
```
In Nuxt, render these in a client context (`` 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
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000). The kundli renders.
**Tip: First render shows a brief blank state while the component code loads from the CDN (~85 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 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](#copy-paste-widgets-no-code) above.
```html
My astrology page
```
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.
**Warning: 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](/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.
```html
```
## 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.
```bash
npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/vedic-kundli.json
```
Use the wrapper:
```tsx
import { RoxyVedicKundli } from '@/components/roxy-ui/vedic-kundli';
export default async function Page() {
const data = await fetchKundliFromYourServer();
return ;
}
```
The wrapper file is a starter you own. Open it and customize freely.
**Tip: RoxyAPI 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 |
|---|---|---|
| `` | Western astrology | Natal chart wheel with planet glyphs and aspect lines |
| `` | Western astrology | Daily, weekly, or monthly horoscope card |
| `` | Western astrology | Dual-wheel synastry plus inter-aspects table |
| `` | Western astrology | Natal and transit aspects with chart-pattern detection |
| `` | Western astrology | Moon phase card and calendar grid |
| `` | Western astrology | Planetary lines (MC, IC, ascendant, descendant) over a world map |
| `` | Western astrology | Relocated chart wheel plus a what-changes panel for a new city |
| `` | Western astrology | Azimuth compass of planetary directions from the birthplace |
| `` | Western astrology | Asteroids, Lilith, progressions, solar arc, or Arabic lots, columns adapt to the response |
| `` | Western astrology | Fixed-star conjunctions to natal planets and angles |
| `` | Western astrology | Annual profection: profected house, sign, and lord of the year |
| `` | Vedic astrology | South or North Indian kundli layout |
| `` | Vedic astrology | Tithi, vara, nakshatra, yoga, karana, plus muhurtas |
| `` | Vedic astrology | Vimshottari mahadasha through sookshma, drill-down at every level |
| `` | Vedic astrology | Manglik, Kalsarpa, Sade Sati severity, exceptions, remedies |
| `` | Vedic astrology | 36-point Ashtakoota with eight Koot sub-scores |
| `` | Vedic (KP system) | KP planets with sub-lord and sub-sub-lord columns |
| `` | Numerology | Life Path, Expression, Personal Year, full chart |
| `` | Tarot | Single card with upright and reversed flip |
| `` | Tarot | Three-card, Celtic Cross, love, career spreads |
| `` | Biorhythm | Daily bars, multi-day forecast, critical days |
| `` | I Ching | Hexagram with trigrams, judgment, image, changing lines |
| `` | Human Design | Nine-center bodygraph with type, authority, profile, channels, and gates |
| `` | Human Design | Two-person connection chart of the channels they form together |
| `` | Forecast | Cross-domain timeline of upcoming transits and events by date |
| `` | Crystals | Crystal gallery by chakra, element, or zodiac sign |
| `` | Dreams | Dream symbol meaning and full interpretation |
| `` | Angel Numbers | Angel number meaning with spiritual, love, and career sections |
| `` | Reference | Glossary card for any sign, planet, rashi, gate, center, or number lookup |
| `` | Cross-domain | Score card with category breakdown |
| `` | Helper | Debounced city search, fires `roxy-location-select` event |
| `` | Helper | Schema-driven form for any endpoint |
Full live preview of every component at [roxyapi.github.io/ui](https://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 (``).
That is why the copy-paste snippets on the [widgets gallery](/widgets) and the [component catalog](/ui) 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:
```html
```
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:
```ts
import '@roxyapi/ui';
import '@roxyapi/ui/locales/es';
```
The [widgets gallery](/widgets) and the [component catalog](/ui) 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 that a widget draws for itself is English today.** Its field labels come from the API reference. If you need a translated form, collect the birth details with your own form and pass the response to the component instead, which is [Path B](#path-b-plain-html-zero-build-step) above.
- **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 CSS custom properties on `:root`. Override globally to match your brand.
```css
:root {
--roxy-bg: #fafafa;
--roxy-fg: #0a0a0a;
--roxy-muted: #71717a;
--roxy-border: #e4e4e7;
--roxy-accent: #f59e0b;
/* Derived from --roxy-accent. Do not set it: you would pin it to one hue. */
--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:
```css
roxy-natal-chart {
--roxy-accent: #ec4899;
--roxy-radius-md: 8px;
}
```
The live preview at [roxyapi.github.io/ui](https://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:
```css
@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.
```tsx
import { RoxyLocationSearch } from '@roxyapi/ui-react';
{
console.log(e.detail.latitude, e.detail.longitude, e.detail.timezone);
}}
/>
```
In vanilla HTML, listen the standard way:
```html
```
## Common gotchas
### `[object Object]` in the rendered chart
You passed the SDK envelope instead of the unwrapped response.
Wrong:
```ts
const response = await roxy.vedicAstrology.generateBirthChart({...});
element.data = response;
```
Right:
```ts
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](/account).
- 429 `rate_limit_exceeded`: monthly quota burned. Quota resets on the 1st at 12:00 AM UTC.
### `'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 (~85 KB gzipped) on mount. Render a fallback while data is null, or preload the bundle in your ``:
```tsx
```
### 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 ``.
### 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 ``.
- [ ] 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](https://roxyapi.github.io/ui/). Theme tokens, copy-paste integration snippets, every component rendered against real responses.
- **Source code** at [github.com/RoxyAPI/ui](https://github.com/RoxyAPI/ui). MIT licensed. Issues, contributions, and release notes welcome.
- **Catalog page** at [roxyapi.com/ui](/ui) for distribution surfaces and FAQ.
- **SDK reference** at [/docs/sdk](/docs/sdk) for every endpoint method.
- **Get an API key** at [roxyapi.com/pricing](/pricing). Instant delivery, no approval queue.
## Frequently asked questions
### Is RoxyAPI 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.
### What languages does RoxyAPI UI support?
Eight: English, Turkish, German, Spanish, Hindi, Portuguese, French, and Russian. Readings and the planet, sign, and aspect names come back in the language you ask for. On-screen labels follow it on the charts that carry a translated label set, and fall back to English elsewhere rather than breaking.
### How do I show a chart in Spanish?
Add one line beside the component script, pointing at the Spanish labels: `https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/locales/es.js`. If the page itself is Spanish, that is all you need, because a component reads the language off the page it is embedded in. If the page is in another language, add `lang="es"` to the component as well.
### Do I have to set the language on every widget?
No. A component reads the `lang` attribute on the page it is embedded in, so a Spanish or Hindi site localizes with no per-widget change. Set `lang` on a component only when you want to fix its language regardless of the page.
### Why is my chart in Spanish but the headings are still English?
The labels a component writes itself ship as a separate file per language, so English sites download nothing extra. Add the line for your language, shown in [Languages and localization](#languages-and-localization) above, and the headings follow.
### Are the widget input forms translated?
Not yet. The form a widget draws for itself is English today, even when the reading it produces is not. If you need a translated form, collect the birth details with your own form and pass the response to the component, which is Path B above.
### 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?
~85 KB gzipped for the full bundle from the CDN. ~9-21 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 `` element renders any response shape as a structured table. New endpoints work out of the box; bespoke components ship as the catalog grows.