@roxyapi/ui-vue

Live demo: https://roxyapi.com/ui. Every component rendered against real API responses, light + dark, with the React/shadcn install command per card.

UI component library for the RoxyAPI catalog. Drop astrology, tarot, numerology, and every other RoxyAPI domain into any framework with one script tag or one npm install. Stateless components, typed responses, theme-agnostic. Beautiful defaults out of the box; the look is yours after that.

Theme-agnostic, every component

Light, dark, your brand. A handful of base tokens style the whole library and everything else derives from them, so one line restyles every component: --roxy-accent moves every accent mark, accent text and focus ring, --roxy-font-sans every heading and label, --roxy-radius every corner. The default look adapts to your page: it inherits your font, keeps the ink neutral and the borders hairline, and spends one restrained accent. No class overrides, no rebuild, no Tailwind required. Customize live at https://roxyapi.com/ui with the Theme menu and the Customize colors dialog (a picker per colour token, a copy-paste snippet).

:root {
  /* Page and ink. The card, the secondary ink, the muted text and every hairline derive from these two. */
  --roxy-bg: #ffffff;
  --roxy-fg: #0a0a0a;

  /* Brand. The text-safe shade (--roxy-accent-ink) and the focus ring (--roxy-ring) derive from it. */
  --roxy-accent: #4a6297;

  /* Status. Each derives its own -fg ink for text on a tint of it. */
  --roxy-success: #16a34a;
  --roxy-warning: #ea580c;
  --roxy-danger: #dc2626;
  --roxy-info: #0284c7;

  /* Type, space, shape, motion. Leave the font unset to keep your page font. */
  --roxy-font-sans: 'Inter', system-ui;
  --roxy-text-base: 1rem;
  --roxy-space-unit: 0.25rem;
  --roxy-radius: 6px;
  --roxy-motion-duration: 200ms; /* 0ms when prefers-reduced-motion */
}

[data-theme="dark"] {
  --roxy-bg: #0a0a0a;
  --roxy-fg: #fafafa;
  /* Only if you want a different accent in dark. Omit it to keep the default. */
  --roxy-accent: #92aade;
}

Pick a tone, set the bases, every chart and card follows. Named presets ship as one stylesheet each (Rosewater, Eucalyptus, Kiln, Moonlit, and Celeste, the roxyapi.com look), each naming a default font pair that font on a component overrides; only the pair in use loads, from where the components are served. Full token reference, the presets and the drawing hooks at THEMING.md. See the FAQ for switching between light and dark at runtime.

Gallery

Every chart, table, and card adapts to light and dark automatically. Hover any image on GitHub to inspect tooltips.

Western astrology

Vedic astrology

Human Design and forecast

Chinese astrology and feng shui

Other domains

Tables, cards, forms, and helper components in the live demo.

Why developers use Roxy UI

• One API key. Charts, tables, cards, forms for every domain in the catalog.
• Works in React, Vue, Svelte, Angular, Solid, vanilla HTML, WordPress.
• Stateless. Caller fetches via @roxyapi/sdk, passes the response as data.
• Theming via CSS custom properties. No Tailwind required, no class-name overrides.
• A11y zero violations under axe-core. Keyboard navigation. Reduced-motion honored.
• Tree-shake friendly. Tight bundle budget enforced in CI.

Start with one component

Fetch with the typed SDK, pass data to the component. No glue code.

import { createRoxy } from '@roxyapi/sdk';
import { RoxyHoroscopeCard } from '@roxyapi/ui-react';

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

const { data } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });

return <RoxyHoroscopeCard data={data} />;

Then expand into natal charts, kundli, dasha, tarot, and every other domain. The SDK returns data, the component renders it; the same pairing holds for every component in the catalog.

Pass data, not the envelope. The SDK returns { data, error, request, response }. Pass data, or the component renders [object Object]. This is the most common integration bug.

The key stays on your server. Vanilla HTML or a server-rendered page fetches the same way, then inlines the JSON into the component: no build step, no key in the browser. Try every component in the live demo, each with Preview, Code, and shadcn tabs and a live color customizer.

Install

npm install @roxyapi/ui-vue

One package. No peer install, no stylesheet to link, no compilerOptions.isCustomElement, no config change. Every response type is exported from the package, so nothing else is needed to be fully typed.

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

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

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

For frameworks that consume custom elements directly (Svelte, Angular, Solid, vanilla HTML, WordPress) install @roxyapi/ui instead.

npm install @roxyapi/ui

Quick start

import { createRoxy } from '@roxyapi/sdk';
import '@roxyapi/ui';

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

const { data: cities } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
const { latitude, longitude, timezone } = cities.cities[0];

const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
	body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
});

document.querySelector('roxy-vedic-kundli')!.data = kundli;

Always call /location/search first. Every chart endpoint expects latitude, longitude, and timezone.

Timezone format. RoxyAPI accepts both forms: a decimal-hour offset (5.5 for IST, -5 for EST) or an IANA name ('Asia/Kolkata', 'America/New_York'). Pick one and stay consistent. /location/search returns both, timezone as the IANA name and utcOffset as the decimal hours; the decimal form is shorter and the examples on this page use it. The IANA form is correct over DST boundaries when historical accuracy matters.

Render an AI tool result

It ships inside @roxyapi/ui, @roxyapi/ui-react and @roxyapi/ui-vue, so whichever one you already installed has it and there is nothing else to add.

Your model calls a Remote MCP tool at roxyapi.com/mcp/{domain} and hands you back a tool name and a JSON string. componentForTool(name) turns that name into the component that draws it, so a chat answer shows a real tarot spread or a real chart instead of a wall of fields. It works in any chat UI that lets you render your own markup for a tool result.

import { componentForTool } from '@roxyapi/ui';

const found = componentForTool(toolName);
if (found) {
	const el = document.createElement(found.tag);
	for (const [name, value] of Object.entries(found.attrs ?? {})) el.setAttribute(name, value);
	el.data = JSON.parse(result.content[0].text);
	container.append(el);
}

In React, pascal is the export name, so a namespace import renders it directly:

import * as RoxyUI from '@roxyapi/ui-react';
import { componentForTool } from '@roxyapi/ui-react/tool-component';

export function ToolWidget({ toolName, output }: { toolName: string; output: string }) {
	const found = componentForTool(toolName);
	if (!found) return null;
	const Component = RoxyUI[found.pascal as keyof typeof RoxyUI] as React.ComponentType<{ data: unknown }>;
	return <Component data={JSON.parse(output)} {...found.attrs} />;
}

A compact tool result is decoded for you, and a name a host prefixed with its server (roxy_tarot:post_tarot_daily) resolves the same as a bare one. Full recipe, with the vendor connectors and the Vercel AI SDK: https://roxyapi.com/docs/tutorials/ai-chat-widgets. Runnable page: examples/vanilla/tool-result.html.

The lookup also ships on its own path, @roxyapi/ui/tool-component and the same subpath on both framework packages, for a module that decides WHICH component to render and never renders one: a server component, a route handler, a worker. It carries componentForTool, expandCompact and the name table, and no elements, so nothing in that file pulls in the library.

import { componentForTool } from '@roxyapi/ui-react/tool-component';

Branded reports

<roxy-report> turns any report the API publishes into a form on your page and a finished document under your brand. The visitor fills the birth details the report asks for, with the same city search and pickers as every widget, and receives the document as a PDF download or in place on the page.

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js" defer></script>
<roxy-report
  report="natal"
  publishable-key="pk_live_YOUR_KEY"
  brand-name="Luna Rivera Astrology"
  brand-footer="Book a reading at example.com"
  brand-color="#1e293b"
  brand-accent="#b45309"
  font="jost"
  theme="moonlit"
></roxy-report>

| Attribute | What it does | |---|---| | report | Which report: natal, synastry, kundli, matchmaking, yearly-forecast, human-design, bazi, numerology, tarot. The published ids are the report values on the roxy-report endpoints in components-catalog.json. Unset, the first one is used | | format | pdf (default) offers the document as a download named after the report; html shows it in place, sized to its content | | brand-name | Your business or practitioner name on the cover and every page | | brand-logo | An HTTPS URL of your logo, printed on the cover | | brand-footer | A line at the foot of every page, such as a disclaimer or a booking note | | brand-color, brand-accent | Your two colours, as #rgb or #rrggbb, on the document and on the form | | font | A key from fonts[] in components-catalog.json, on the document and on the form | | theme | A key from themes[] in components-catalog.json: the document prints in that preset. Link the same preset stylesheet (see Theme presets in THEMING.md) and the form matches it | | hide-readings | The document carries the charts and the data without the written reading | | publishable-key | Your pk_ key, or submit-url to send the request through your own server | | lang | The language of the form and the document |

React and Vue take the same settings as props (report, format, brandName, brandLogo, brandFooter, brandColor, brandAccent, font, theme, hideReadings). Every branding value is optional, and the document carries no mark but yours.

A request the API turns down reads as one sentence in the page language above the API message: details to check, a site the key does not allow, too many requests, or a busy moment. A field the API names is marked under its own input. The page hears roxy-validation-error when a required field is missing and roxy-render-error if a result cannot be drawn.

The one-tag widget takes the same settings as data- attributes: <div data-roxy-widget="report" data-report="kundli" data-brand-name="Luna Rivera Astrology" data-publishable-key="pk_live_YOUR_KEY"></div>.

Server-rendered, no JavaScript wiring

Server-rendered and cached pages (WordPress, JSX SSR, static HTML) cannot always run JavaScript to set the data property per element. Render the response into a child <script type="application/json" class="roxy-data"> on the server instead. The component reads it on load. No per-element script, no API key in the browser.

Serialize with the shipped helper, never a bare JSON.stringify. @roxyapi/ui exports roxyDataScript(data) (the full <script class="roxy-data">…</script> element) and serializeRoxyData(data) (just the escaped JSON). They escape <, >, and & so a string field containing </script> cannot break out of the block and corrupt the page.

Load the bundle once anywhere on the page. It registers every roxy-* element and loads the design tokens, so every component on the page renders themed, in light or dark, from that single tag. Nothing else to add.

No-JavaScript fallback

The two modes degrade differently, and only one of them can be rescued.

Controlled mode (the <script class="roxy-data"> island above) already holds the reading in the page. Render it server-side as ordinary HTML alongside the island and put that markup inside the element. Components render into a shadow root and none of them expose a <slot>, so light-DOM children are painted only while the element is un-upgraded, and disappear the moment the bundle registers it. You get the server HTML without JavaScript and the live component with it, from the same markup, with no flash of both.

Form mode (a pk_ key or a submit-url, no data) is a self-fetch widget: it cannot work without JavaScript, because there is nothing to render until the visitor submits the form. Give it a light-DOM fallback that says so and links out.

<roxy-natal-chart publishable-key="pk_live_…">
  <!-- Painted only when JavaScript is off. Replaced by the component otherwise. -->
  <p>JavaScript is required to generate this chart.
     <a href="https://roxyapi.com/products/astrology">Open it on roxyapi.com</a>.</p>
</roxy-natal-chart>

A <noscript> block works too, and is the safer choice if you also need to hide the fallback from screen readers once the component takes over.

import { roxyDataScript } from '@roxyapi/ui';

const { data } = await roxy.astrology.generateNatalChart({ body });
const html = `
  <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js" crossorigin="anonymous" defer></script>
  <roxy-natal-chart>${roxyDataScript(data)}</roxy-natal-chart>
`;

The emitted markup:

<roxy-natal-chart>
	<script type="application/json" class="roxy-data">{ "planets": [ ... ], "houses": [ ... ], "aspects": [ ... ] }</script>
</roxy-natal-chart>

The component picks up the embedded JSON when no data property has been set. The JavaScript property always wins: assign element.data and the markup is ignored, so dynamic pages and server-rendered pages share one component with no branching. You can nest a server-rendered HTML fallback inside the same element for no-JavaScript and crawler views; the component leaves it untouched and reads only the marked script.

This is how the WordPress plugin renders: PHP fetches the response server-side, caches it, and embeds it in the page. The same shape works in any framework that emits HTML.

Writing the tag in React or Next.js? @roxyapi/ui-react/jsx types every roxy-* tag and its attributes, so a server component can render one directly and still be checked:

import '@roxyapi/ui-react/jsx';

export default function Page() {
	return <roxy-tarot-spread spread="three-card" hide-readings />;
}

One import anywhere in the project types the tags everywhere in it. The typings carry attributes only, which is what markup can carry: a page that passes a response uses the React or Vue component, which sets data as a property. Your tsconfig.json needs moduleResolution on bundler, node16 or nodenext, because the older node10 resolution ignores the package export map.

Draw a chart on the server

@roxyapi/ui/charts turns a response into the same <svg> its component draws, as a string, with no browser and no rendering library: a PDF, an email, a static page or an image job gets the chart a visitor sees on the page.

import { createRoxy } from '@roxyapi/sdk';
import {
	bodygraphSvg,
	kundliSvg,
	natalWheelSvg,
	synastryWheelSvg,
	toKundliViewModel,
} from '@roxyapi/ui/charts';
import '@roxyapi/ui/locales/es';

const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data: natal } = await roxy.astrology.generateNatalChart({ body, throwOnError: true });
const wheel: string = natalWheelSvg(natal, { lang: 'es' });

const { data: birth } = await roxy.vedicAstrology.generateBirthChart({ body, throwOnError: true });
const kundli: string = kundliSvg(toKundliViewModel(birth.meta), { style: 'south' });

synastryWheelSvg takes a synastry response and bodygraphSvg a bodygraph response the same way. lang writes the words the chart adds in that language once its locale is imported; English needs no import.

The paint is a stylesheet per chart, published beside the tokens: styles/charts/natal-wheel.css, synastry-wheel.css, kundli.css and bodygraph.css. Link tokens.css, a theme if you use one, and the chart sheet next to the string, and it paints exactly as the component does, in light and dark:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/tokens.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/charts/natal-wheel.css">

The same path carries the published font pairs as data: ROXY_FONTS (keyed by the fonts[] keys in components-catalog.json, each with its name and its sans and display stacks) and fontFaces(key), the files a pair is drawn with, so a server sets the type a page shows.

moonSvg({ illumination, waxing, hemisphere, eclipse, size, lang }) draws the Moon every component shows, from its lit fraction (0 to 100): the lit side, earthshine, the maria and a lunar or solar eclipse, turned for the Southern Hemisphere with hemisphere: 'south'. lunarDayMoon(n) gives the Moon of a tithi or a lunar day. Paint it with styles/charts/moon.css, or take only the lit outline on the unit disc with litPath(k, waxing).

Every planet, sign, aspect, trigram and hexagram glyph draws in Roxy Symbols, a symbol face that ships in this package. From the CDN script it loads by itself. In an npm build, import @roxyapi/ui/styles/fonts/symbols.css once, beside tokens.css; on a server, symbolFontFaces() lists its files, fontFaceCss(faces, base) writes the @font-face rules for them served under base, and SYMBOL_FAMILY names it. The glyphs themselves come from planetGlyph, signGlyph, aspectSymbol, trigramGlyph and hexagramGlyph(n), each returning undefined for a name it does not know, plus RETROGRADE_MARK, MUTUAL_MARK and BIRTHPLACE_MARK.

Most-used components per domain

The highest-demand components by domain, in the order you are most likely to ship them. Each pairing shows the SDK call that returns the response shape the component renders. Spec change in the API translates to typed change at the component boundary; the pairing below is derived from the live OpenAPI spec, not invented. Full catalog in the Components table.

1. Western astrology (natal chart, daily horoscope, synastry)

The natal wheel, the daily horoscope and the synastry comparison, which is what most astrology products ship first. Zodiac dating apps, natal chart products, horoscope features and lunar-cycle wellness apps all build on these three.

import { createRoxy } from '@roxyapi/sdk';
import { RoxyNatalChart, RoxyHoroscopeCard, RoxySynastryChart } from '@roxyapi/ui-react';

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

// 1. Natal chart. The #1 Western query, called on every onboarding.
const { data: natal } = await roxy.astrology.generateNatalChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
});
<RoxyNatalChart data={natal} />

// 2. Daily horoscope. Highest per-user call frequency in the catalog, drives DAUs and push.
const { data: horoscope } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
<RoxyHoroscopeCard data={horoscope} />

// 3. Synastry. The dating-app pro-tier feature, full inter-aspect analysis between two charts.
const { data: synastry } = await roxy.astrology.calculateSynastry({
  body: {
    person1: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
    person2: { date: '1992-07-22', time: '09:00:00', latitude: 19.07, longitude: 72.87, timezone: 5.5 },
  },
});
<RoxySynastryChart data={synastry} />

2. Vedic astrology (kundli, panchang, dasha, dosha, KP, ashtakavarga, divisional)

The deepest domain in the catalog. Kundli, panchang, dasha, dosha, KP horary, ashtakavarga and the divisional charts (D9 Navamsa, D10 Dasamsa) are what matrimonial platforms, kundli generators, muhurat apps and professional readers need, and each one has a component rather than a raw payload.

import {
  RoxyVedicKundli, RoxyVedicPlanetsTable, RoxyPanchangTable,
  RoxyDashaTimeline, RoxyDoshaCard, RoxyKpChart, RoxyAshtakavargaGrid,
  RoxyDivisionalChart,
} from '@roxyapi/ui-react';

// Kundli + positions table share a single API call (the same response renders both).
const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
});
<RoxyVedicKundli data={kundli} chart-style="south" />
<RoxyVedicPlanetsTable data={kundli} />

// Panchang. Tithi, nakshatra, yoga, karana, rahu kaal, abhijit muhurta in one call.
const { data: panchang } = await roxy.vedicAstrology.getDetailedPanchang({
  body: { date: '2026-04-22', latitude: 19.07, longitude: 72.88 },
});
<RoxyPanchangTable data={panchang} />

// Vimshottari dasha. The 120-year planetary period timeline.
const { data: dasha } = await roxy.vedicAstrology.getMajorDashas({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
});
<RoxyDashaTimeline data={dasha} period="major" />

// Mangal Dosha. Most-asked matrimonial question in India.
const { data: dosha } = await roxy.vedicAstrology.checkManglikDosha({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
});
<RoxyDoshaCard data={dosha} />

// KP chart. The horary timing tool, sub-lord stellar hierarchy on every cusp.
const { data: kp } = await roxy.vedicAstrology.generateKpChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
});
<RoxyKpChart data={kp} />

// Ashtakavarga. Bindu strength heatmap with Sarva, Bhinna, Shodhya Pinda views.
const { data: ashtaka } = await roxy.vedicAstrology.calculateAshtakavarga({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
});
<RoxyAshtakavargaGrid data={ashtaka} />

// Divisional chart (D9 Navamsa shown). `division` is the integer 9, not "D9".
// Supported: 2, 3, 4, 7, 9, 10, 12, 16, 20, 24, 27, 30, 40, 45, 60.
const { data: d9 } = await roxy.vedicAstrology.generateDivisionalChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5, division: 9 },
});
<RoxyDivisionalChart data={d9} />

3. Forecast (transits, cross-domain timeline)

One stateless call merges Western transits, Vedic Vimshottari dasha boundaries, and biorhythm critical days into a single significance-scored, time-ordered timeline. Built for forecast feeds, transit alerts, and timing tools. No coordinates needed.

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

// Transit forecast. The demand leader. Western transit-to-natal aspects, sign
// ingresses, and retrograde stations over the window.
const { data: transits } = await roxy.forecast.forecastTransits({
  body: { birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 } },
});
<RoxyForecastTimeline data={transits} />

// Cross-domain timeline. The same window merged with Vedic dasha boundaries and
// biorhythm critical days into one significance-scored timeline.
const { data: timeline } = await roxy.forecast.generateTimeline({
  body: {
    birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
    domains: ['western', 'vedic', 'biorhythm'],
  },
});
<RoxyForecastTimeline data={timeline} />

4. Human Design (bodygraph)

A self-knowledge system computed from the same ephemeris as Western astrology, laid over the I Ching gate wheel and nine chakra-style centers. Self-discovery apps, dating and compatibility products, and AI coaching bots render the full bodygraph. No coordinates needed; Human Design uses the birth instant, not the observer location.

The response is a reading, not a set of labels: the type, strategy, authority, profile, and definition each arrive with the text that explains them, every defined channel and every center carry their own interpretation, and each of the activations carries a gate meaning and the meaning of its line. <RoxyBodygraph> lays that out for you. The chart and the identity read at a glance, the Design moment prints in the header on the UTC clock so the chart can be checked against any other calculator on the instant itself, and every body of prose sits behind a disclosure, so one component renders a complete reading without becoming a wall of text.

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

// Full bodygraph. The head term every Human Design app leads with ("human design chart").
// Type, strategy, authority, profile, the nine centers, channels, and every gate
// activation in one call. Pass the birth instant only, no latitude or longitude.
const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
});
<RoxyBodygraph data={bodygraph} />

Every interpretation is localized. Ask for the language on the request and the component renders it, because the component prints the prose the API returned and holds no copy of its own.

const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
  query: { lang: 'de' },
});

5. Chinese astrology (four pillars, luck pillars, zodiac, almanac)

The BaZi chart a reading is built on, the ten-year luck pillars that time it, the twelve-animal zodiac, and the almanac people actually consult to pick a date. Fits date-selection tools, Chinese-new-year features and East Asian wellness apps.

import { RoxyBaziChart, RoxyZodiacCard, RoxyAlmanacDay } from '@roxyapi/ui-react';

// Four pillars. Stem over branch per pillar, hidden stems, Ten Gods, element balance.
const { data: bazi } = await roxy.chineseAstrology.generateBaziChart({
  body: { date: '1990-01-15', time: '14:30:00', timezone: 'America/New_York' },
});
<RoxyBaziChart data={bazi} />

// The animal a birth date falls in, on the classical year boundary.
const { data: sign } = await roxy.chineseAstrology.calculateZodiacAnimal({
  body: { date: '1990-01-15' },
});
<RoxyZodiacCard data={sign} mode="sign" />

// Almanac day. What the day favours, what it avoids, and the animal it clashes with.
const { data: day } = await roxy.chineseAstrology.getAlmanacDay({ path: { date: '2026-09-08' } });
<RoxyAlmanacDay data={day} mode="day" />

6. Feng shui (kua number, eight mansions, flying stars)

A person's Kua number and the eight directions it ranks for them, plus the Xuan Kong flying-star plate for a building. Fits home and office consultation tools, property apps and annual-forecast features.

import { RoxyKuaCard, RoxyFlyingStarChart } from '@roxyapi/ui-react';

// Kua number and the full Eight Mansions map, four favourable sectors and four not.
const { data: mansions } = await roxy.fengShui.generateEightMansions({
  body: { date: '1990-01-15', gender: 'female' },
});
<RoxyKuaCard data={mansions} mode="mansions" />

// Flying star plate for a building, from its facing degrees and construction period.
const { data: plate } = await roxy.fengShui.generateFlyingStarChart({
  body: { facingDegrees: 175, period: 9 },
});
<RoxyFlyingStarChart data={plate} mode="natal" />

7. Mesoamerican astrology (Tzolkin day sign, Calendar Round)

The 260-day Tzolkin day sign and trecena for any date, plus the full Calendar Round: Haab date, Long Count and year bearer, across four correlation constants. Fits Mayan-zodiac calculators, day-sign lookup tools and Mesoamerican-calendar content.

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

// Tzolkin day sign. The lead query: day sign, coefficient, the trecena it falls in, and the composed nawal reading.
const { data: day } = await roxy.mesoamericanAstrology.calculateTzolkin({
  body: { date: '1990-01-15' },
});
<RoxyMayanDaySign data={day} mode="day" />

// Calendar Round. The fuller chart: Tzolkin and Haab dates, the Long Count, and the year bearer.
const { data: chart } = await roxy.mesoamericanAstrology.generateMayanChart({
  body: { date: '1990-01-15' },
});
<RoxyMayanDaySign data={chart} mode="chart" />

8. Vastu (Purusha Mandala, entrance pada)

The 81-pada Vastu Purusha Mandala projected over any plot shape, and the entrance pada a main door falls on with its verse effect. Fits Vastu consultation tools, floor-plan apps and entrance-direction calculators.

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

// Vastu Purusha Mandala. Every pada over the plot, with the devata holding it and the brahmasthan marked.
const { data: mandala } = await roxy.vastu.generateMandala({
  body: { plot: { width: 30, depth: 40, unit: 'feet' } },
});
<RoxyVastuMandala data={mandala} mode="mandala" />

// Entrance pada. Which of the 32 perimeter padas the main door falls on, and the verse effect for it.
const { data: entrance } = await roxy.vastu.calculateEntrancePada({
  body: { plot: { width: 30, depth: 40, unit: 'feet' }, facing: 'East', doorPosition: 0.4 },
});
<RoxyVastuMandala data={entrance} mode="entrance" />

9. Numerology (life path, full chart, personal year)

Life path, the full chart, and the personal year. The easiest domain to integrate: a name and a birth date are enough, with no birth time and no coordinates.

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

// Life Path. The #1 numerology keyword, every calculator page starts here.
const { data: lp } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 1, day: 15 },
});
<RoxyNumerologyCard data={lp} type="life-path" />

// Full numerology chart. Premium one-shot: all six core numbers plus karmic, personal year.
const { data: chart } = await roxy.numerology.generateNumerologyChart({
  body: { fullName: 'Jane Smith', year: 1990, month: 1, day: 15 },
});
<RoxyNumerologyCard data={chart} type="chart" />

// Personal Year. Annual forecast, drives January traffic spikes.
const { data: pyear } = await roxy.numerology.calculatePersonalYear({
  body: { month: 1, day: 15, year: 2026 },
});
<RoxyNumerologyCard data={pyear} type="personal-year" />

10. Kabbalah (gematria)

Gematria for a Latin or Hebrew name: every candidate Hebrew spelling, the value under each cipher, and the words that share it. Fits name-numerology tools, Hebrew-calendar apps and Kabbalah content.

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

// Gematria. Every candidate Hebrew spelling of a Latin name, the value under each cipher, and equal-value words.
const { data: gematria } = await roxy.kabbalah.calculateGematria({
  body: { text: 'Sarah', latinCiphers: true },
});
<RoxyGematria data={gematria} />

11. Tarot (daily card, three-card, Celtic Cross)

Draw a single daily card, a three-card spread, or a full Celtic Cross. The card database is stable reference data, so fetch it once and cache it rather than calling per render.

import { RoxyTarotCard, RoxyTarotSpread } from '@roxyapi/ui-react';

// Daily card. Stickiest tarot feature. Seed per user for deterministic once-per-day behavior.
const { data: daily } = await roxy.tarot.getDailyCard({ body: { seed: 'user-42' } });
<RoxyTarotCard data={daily} />

// Three-card past-present-future. Most-drawn spread on every tarot platform.
const { data: three } = await roxy.tarot.castThreeCard({
  body: { question: 'My next quarter', seed: 'user-42' },
});
<RoxyTarotSpread data={three} />

// Celtic Cross. Professional-reader spread. Premium-tier, ten positions.
const { data: cc } = await roxy.tarot.castCelticCross({
  body: { question: 'What should I focus on?', seed: 'user-42' },
});
<RoxyTarotSpread data={cc} />

12. Biorhythm (daily, forecast)

Physical, emotional and intellectual cycles from a birth date alone, as a daily reading or a forward forecast with the critical days marked. Fits wellness, productivity, sports and couples apps.

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

// Daily biorhythm. Physical, emotional, intellectual, intuitive, plus seven extended cycles.
// Seeded for stable "biorhythm of the day" features; pass a userId for per-user determinism.
const { data: bio } = await roxy.biorhythm.getDailyBiorhythm({
  body: { seed: 'user-42', date: '2026-04-23' },
});
<RoxyBiorhythmChart data={bio} />

// Multi-day forecast. Best-day / worst-day planner for calendar and coaching products.
const { data: forecast } = await roxy.biorhythm.getForecast({
  body: { birthDate: '1990-01-15', startDate: '2026-04-01', endDate: '2026-04-30' },
});
<RoxyBiorhythmChart data={forecast} mode="forecast" />

13. Ayurveda (dosha constitution)

The three-humour constitution computed from a birth chart: vata, pitta and kapha shares as one blend, with the classical factors and verse citations behind it. Fits wellness apps, Ayurveda consultation tools and birth-chart products adding a dosha reading.

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

// Ayurvedic constitution. Vata, pitta and kapha shares from the birth chart, with the cited factors behind the blend.
const { data: constitution } = await roxy.ayurveda.calculateAyurvedicConstitution({
  body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
});
<RoxyDoshaConstitution data={constitution} />

14. I Ching (cast a reading, hexagram lookup)

Cast a reading with its changing lines and the hexagram it transforms into, or look up any of the 64 figures directly. Fits meditation apps, decision-making tools and wisdom chatbots.

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

// Cast a reading. Active divination, primary hexagram plus changing lines and transformed hexagram.
const { data: reading } = await roxy.iching.castReading({ query: { seed: 'user-42' } });
<RoxyHexagram data={reading} />

// Random hexagram. One-shot daily-hexagram surface for ambient apps.
const { data: random } = await roxy.iching.getRandomHexagram();
<RoxyHexagram data={random} />

Pairing rule. The SDK return value already matches the data prop on every component. No field renames, no glue code. When a new endpoint ships in the spec, the SDK and the component types regenerate together; the same pattern keeps working.

API keys

Get a key at https://roxyapi.com/account.

Two key types. Secret keys (sk_*) grant full account access: use them server side only (Node, Bun, Hono, Next.js route handlers, Workers). Never commit one, never ship one in a client bundle. Publishable keys (pk_live_* / pk_test_*) are browser-safe: mint one, register the origins you embed on, and any other origin gets a 403 at the gateway.

Two ways to feed a component, and the key rule for each:

• Controlled (recommended for production). Your server fetches with the secret key and passes the response in via the data property or a roxy-data JSON island. No key of any kind reaches the browser. This is what the WordPress plugin and the server-rendered patterns do.
• Self-fetch (no backend). Give the component a publishable-key and it renders its own form and fetches in the browser. data-endpoint is optional: without it the component fetches its default endpoint, its config attribute (mode, period, type, spread, detail) picks another of the endpoints it renders, and data-endpoint set to a spec path (astrology/lilith on <roxy-positions-table>) chooses any endpoint it renders. Only publishable keys work here: a secret key, or the pk_live_YOUR_KEY sample left in a copied snippet, is refused client-side, so the component shows the reason in place of its form, sends nothing and raises a validation error. A secret key cannot leak through self-fetch.

Set ROXY_API_KEY to your secret key in your server env for the server-side SDK examples on this page. For self-fetch embedding with no backend, use a publishable key (see the fully client-side pattern in AGENTS.md).

The self-fetch form renders spec-driven inputs (a zodiac tile picker, a boolean toggle, native date and time, a city search wherever the request takes coordinates or a timezone, and one card per record for a request that takes several, with Add and Remove inside the bounds the API declares), collapses optional fields under one Advanced disclosure, reads a lang attribute for localized responses, and prints what the API rejects under the input it rejected, marked and summarised by label. When the page routes RoxyAPI traffic through your own server instead, submit-url alone names the route that answers every request the component makes, the city search included, so no key of any kind reaches the browser; add location-url only to send the city search somewhere else. submit-context takes a JSON object of your own and hands it to that route as context beside the request, which is where a page attaches its own verification data to a submission. For the simplest embed, load dist/cdn/widgets.js and drop one <div data-roxy-widget="{slug}" data-publishable-key="pk_live_...">: with the required attributes present it fetches on mount, otherwise it renders the form. That tag takes data-submit-url, data-location-url and data-submit-context too, so a one-tag embed can route every request through your server and carry no key at all. A single <link> to a theme preset (Rosewater, Eucalyptus, Kiln, Moonlit or Celeste, from the Distribution table) restyles every widget on the page. A list that shows one entry per tile (the dream search, the crystal grid) opens the picked entry in place under its tiles when it holds the key, and every pick also emits roxy-symbol-select for a page that pairs its own card. Any element that carries a key exposes load({ path, method, query }), which fetches one request into it and renders the result as assigned data.

Distribution

| Surface | URL | |---|---| | npm @roxyapi/ui | npmjs.com/package/@roxyapi/ui | | npm @roxyapi/ui-react | npmjs.com/package/@roxyapi/ui-react | | npm @roxyapi/ui-vue | npmjs.com/package/@roxyapi/ui-vue | | jsDelivr CDN (full bundle) | cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js | | jsDelivr CDN (per component) | cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/components/{name}.js | | Widgets auto-mount (one tag, browser keys) | cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js | | Theme presets (one link each, by key: practitioner for Rosewater, eucalyptus, kiln, moonlit, celeste) | cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/themes/{key}.css | | shadcn registry | npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/{name}.json | | Components catalog (JSON: every component, its domain, endpoints, attributes and parts, and the theme presets) | cdn.jsdelivr.net/npm/@roxyapi/ui@latest/components-catalog.json |

Serve from your own domain

Every file a page loads ships in the package dist folder, and each GitHub release attaches the same package as a tarball (package/dist): download roxyapi-ui-{version}.tgz from the latest release, or open any single file in the current dist/cdn folder. Copy dist/cdn and dist/schemas to your server side by side, as they ship, and load cdn/roxy-ui.js (or cdn/widgets.js, or one file from cdn/components/) from there: forms read their schemas from beside the script, and the language files sit in cdn/locales/. Add submit-url and the page talks only to your own domain.

<script src="/roxy/cdn/roxy-ui.js" defer></script>
<script src="/roxy/cdn/locales/es.js" defer></script>
<roxy-natal-chart submit-url="/roxy/proxy"></roxy-natal-chart>

Components

| Element | Domain | Endpoint(s) | What it renders | |---|---|---|---| | <roxy-natal-chart> | Western | POST /astrology/natal-chart | Natal chart wheel with planet glyphs and aspect lines | | <roxy-synastry-chart> | Western | POST /astrology/synastry | Dual-wheel synastry with inter-aspects table | | <roxy-western-planets-table> | Western | POST /astrology/natal-chart | Sign, degree, house, motion columns plus ASC, MC, PoF, Vertex | | <roxy-transits-table> | Western | POST /astrology/transits | Transit planet positions plus optional aspects to a natal chart | | <roxy-transit-wheel> | Western | POST /astrology/transit-aspects | Natal chart on the inner ring, transiting bodies on the outer ring, aspect lines between them | | <roxy-aspects-table> | Western | POST /astrology/aspects, /astrology/transit-aspects, /astrology/aspect-patterns | Aspect rows coloured by nature with orb and strength, plus detected chart patterns | | <roxy-moon-phase> | Western | GET /astrology/moon-phase/{current,upcoming,calendar/...} | Moon phase card and calendar | | <roxy-horoscope-card> | Western | GET /astrology/horoscope/{sign}/{daily,weekly,monthly,yearly} | Daily, weekly, monthly, or yearly horoscope card | | <roxy-astrocartography-map> | Western | POST /astrology/astrocartography | World map of planetary MC, IC, Ascendant, and Descendant lines with per-line interpretations | | <roxy-local-space-compass> | Western | POST /astrology/local-space | Compass dial of planetary azimuth lines from the birthplace, dimmed below the horizon | | <roxy-relocation-wheel> | Western | POST /astrology/relocation-chart | Relocated chart wheel plus the move geometry, angular planets, and planets that change house | | <roxy-positions-table> | Western | POST /astrology/asteroids, /astrology/lilith, /astrology/progressions, /astrology/solar-arc, /astrology/arabic-lots | Body, sign, degree, and per-shape columns (house, motion, formula, or natal arc) plus each reading | | <roxy-ephemeris-table> | Cross | POST /astrology/planets/monthly, /vedic-astrology/planetary-positions/monthly | Per-body sign changes and retrograde windows for the month, over the full daily position grid | | <roxy-fixed-stars> | Western | POST /astrology/fixed-stars | Star to natal point conjunctions with readings, plus a catalog of position, magnitude, nature, and keywords | | <roxy-profection-card> | Western | POST /astrology/profections | Profected house and sign for the year, the lord of the year, its natal placement, and the reading | | <roxy-compatibility-card> | Cross | POST /astrology/compatibility-score, /numerology/compatibility, /biorhythm/compatibility | Score card with category breakdown | | <roxy-vedic-kundli> | Vedic | POST /vedic-astrology/birth-chart | South, North, or East Indian kundli with degree detail and optional Chandra Lagna view | | <roxy-divisional-chart> | Vedic | POST /vedic-astrology/{divisional-chart,navamsa} | Generic divisional varga wheel from D2 Hora to D60 Shashtiamsa | | <roxy-kp-chart> | Vedic (KP) | POST /vedic-astrology/kp/chart | Ascendant, cusps, planets and nodes with KP stellar hierarchy and house meanings | | <roxy-vedic-planets-table> | Vedic | POST /vedic-astrology/birth-chart | Degree, nakshatra, pada, lord, bhava, Baladi, Jagradadi and Deeptadi columns | | <roxy-kp-planets-table> | Vedic (KP) | POST /vedic-astrology/kp/planets | Sub-lord and sub-sub-lord columns | | <roxy-kp-ruling-planets> | Vedic (KP) | POST /vedic-astrology/kp/ruling-planets | Day lord, Moon/Lagna hierarchies, ruling planets, significators with house meanings | | <roxy-ashtakavarga-grid> | Vedic | POST /vedic-astrology/ashtakavarga | Sarva, Bhinna, and Shodhya Pinda views in a tabbed heatmap | | <roxy-shadbala-table> | Vedic | POST /vedic-astrology/shadbala | Six-fold planetary strength bar plus rupas and adequacy badge | | <roxy-dasha-timeline> | Vedic | POST /vedic-astrology/dasha/{current,major,sub/...} | Vimshottari mahadasha, antardasha, pratyantardasha, sookshma and prana, drill-down at every level | | <roxy-guna-milan> | Vedic | POST /vedic-astrology/compatibility | 36-point Ashtakoota with eight sub-scores | | <roxy-panchang-table> | Vedic | POST /vedic-astrology/panchang/{basic,detailed} | 15+ muhurtas in detailed mode | | <roxy-vedic-aspects> | Vedic | POST /vedic-astrology/aspects | Graha drishti rows with aspect type, strength, and orb, plus mutual aspects | | <roxy-hora-table> | Vedic | POST /vedic-astrology/panchang/hora | Day and night planetary hours with ruling planet and window | | <roxy-choghadiya-grid> | Vedic | POST /vedic-astrology/panchang/choghadiya | Day and night Choghadiya muhurta tiles colored by effect | | <roxy-heliacal-table> | Vedic | POST /vedic-astrology/heliacal | Udaya and asta windows for the six visible grahas, the calculation behind Guru Asta and Shukra Asta | | <roxy-vedic-daily> | Vedic | POST /vedic-astrology/daily | Composed Vedic daily reading with the classical rule behind every graha state, the Tara and Chandrabala windows in full, and all three sidereal frames named | | <roxy-kp-finance-card> | Vedic | POST /vedic-astrology/kp/daily-finance | KP daily finance reading with the cusp sub lords, the running dasha lords, the ruling planets and the Moon sub lord windows each scored against the gain and loss houses, weighed into one band for the day | | <roxy-gochara-table> | Vedic | POST /vedic-astrology/transit | Vedic gochara with aspects to the natal chart and the Gochara Kaksha reading drawn as a position within the sign | | <roxy-bhava-bala-table> | Vedic | POST /vedic-astrology/bhava-bala | House strength in rupas and virupas, ranked, with Bhavadhipati, Dig and Drishti Bala shown as proportions of the total | | <roxy-bhav-chalit-table> | Vedic | POST /vedic-astrology/bhav-chalit | The Chalit chart against the Rashi chart, leading with how many grahas move and which, plus the unequal bhava spans | | <roxy-upagraha-table> | Vedic | POST /vedic-astrology/upagraha | Time-based and Sun-based upagrahas with rashi, degree, longitude and nakshatra | | <roxy-chara-karakas> | Vedic | POST /vedic-astrology/chara-karakas | Karaka offices in rank order with graha, degree, scheme, and what each is read for | | <roxy-arudha-padas> | Vedic | POST /vedic-astrology/arudha | Twelve padas with bhava, lord, pada rashi, house from Lagna, and the classical exception marked | | <roxy-yoga-list> | Vedic | GET /vedic-astrology/yoga, /vedic-astrology/yoga/{id}, POST /vedic-astrology/yoga/detect | Filterable yoga cards from the 300 plus yoga catalog, grouped by verdict in detect mode | | <roxy-nakshatra-card> | Vedic | GET /vedic-astrology/nakshatras/{id} | Lord, deity, symbol, characteristics, remedies | | <roxy-dosha-card> | Vedic | POST /vedic-astrology/dosha/{manglik,kalsarpa,sadhesati} | Presence, severity, remedies, scoped effects | | <roxy-numerology-card> | Numerology | POST /numerology/{life-path,expression,soul-urge,personality,birth-day,maturity,daily,personal-day,personal-month,personal-year,chart} | Life path, expression, soul urge, personality, personal year, full chart | | <roxy-compound-number> | Numerology | GET /numerology/compound-number/{number} | Compound 10 to 52 with name, root, nature and meaning | | <roxy-gematria> | Kabbalah | POST /kabbalah/gematria | Values by cipher, every candidate Hebrew spelling with its per letter breakdown, and equal-value words | | <roxy-tarot-card> | Tarot | GET /tarot/cards/{id}, POST /tarot/daily | Single card with upright and reversed flip | | <roxy-tarot-catalog> | Tarot | GET /tarot/cards | Deck gallery tiles with card art, name, and arcana and suit; a pick opens the card in place | | <roxy-tarot-spread> | Tarot | POST /tarot/spreads/{three-card,celtic-cross,love,career,custom}, /tarot/yes-no, /tarot/draw | Spreads with positions and reading | | <roxy-bodygraph> | Human Design | POST /human-design/bodygraph | Nine-center chart with defined and open centers, active channels, and gates, plus the type, strategy, authority, profile, and definition readings, the channels by circuit, the centers, and every activation with its gate and line meaning | | <roxy-hd-type-card> | Human Design | POST /human-design/type, /human-design/profile | Type, strategy, authority, and profile tiles with the aura, signature, and not-self themes, plus the reading behind each label and the profile line keynotes | | <roxy-hd-connection> | Human Design | POST /human-design/connection | Electromagnetic, compromise, and dominance channels between two charts | | <roxy-hd-penta> | Human Design | POST /human-design/penta | Group penta channels split into upper and lower triangles | | <roxy-hd-variables> | Human Design | POST /human-design/variables | The four transformation arrows with direction, color, tone, and base, plus a reading per arrow grouped by layer and the cognition | | <roxy-forecast-timeline> | Forecast | POST /forecast/{timeline,significant-dates,transits} | Date-grouped events across Western, Vedic, and biorhythm domains, weighted by significance | | <roxy-forecast-digest> | Forecast | POST /forecast/digest | Per-window event counts, domain breakdown, and the highest-significance events | | <roxy-bazi-chart> | Chinese | POST /chinese-astrology/bazi/chart | Year, month, day and hour pillars in hanzi with hidden stems, Ten Gods, Na Yin, element balance and interactions | | <roxy-luck-pillars> | Chinese | POST /chinese-astrology/bazi/luck-pillars | Ten-year luck pillars as a strip with ages and years, the annual pillars, and the direction and start age behind them | | <roxy-zodiac-card> | Chinese | POST