@roxyapi/ui-vue

@roxyapi/ui-vue

Live demo: https://roxyapi.github.io/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. Set --roxy-accent on :root and every component follows: the text-safe accent and the focus ring are derived from it, so one line rebrands the whole library. If you theme dark differently, set it in your dark block too, exactly as you would for any design-token system. No class overrides, no rebuild, no Tailwind required. Customize live at https://roxyapi.github.io/ui/ using the Customize dialog (every token, colour picker, copy-paste snippet).

:root {
  /* Surface. --roxy-surface is the card a component paints, so match it to the
     surface you place the component on; --roxy-bg is the field behind an input. */
  --roxy-surface: #ffffff;
  --roxy-bg: #ffffff;
  --roxy-fg: #0a0a0a;
  --roxy-secondary: #475569;
  --roxy-muted: #71717a;
  --roxy-border: #e4e4e7;

  /* Brand. Set the accent; the text-safe shade (--roxy-accent-ink) and the focus
     ring (--roxy-ring) are derived from it, so one line rebrands everything. */
  --roxy-accent: #f59e0b;

  /* Status (each has a -fg variant for WCAG-AA text contrast) */
  --roxy-success: #16a34a;
  --roxy-warning: #ea580c;
  --roxy-danger: #dc2626;
  --roxy-info: #0284c7;

  /* Shape + motion */
  --roxy-radius-md: 8px;
  --roxy-shadow-md: 0 4px 6px -1px rgba(0,0,0,0.08), 0 2px 4px -2px rgba(0,0,0,0.06);
  --roxy-motion-duration: 200ms; /* 0ms when prefers-reduced-motion */
}

[data-theme="dark"] {
  --roxy-surface: #18181b;
  --roxy-bg: #0a0a0a;
  --roxy-fg: #fafafa;
  --roxy-secondary: #94a3b8;
  --roxy-muted: #a1a1aa;
  --roxy-border: #27272a;
  /* Only if you want a different accent in dark. Omit it to keep the default. */
  --roxy-accent: #fbbf24;
}

Pick a tone, set the vars, every chart and card follows. Full token reference at THEMING.md. Live tweaker on the demo site. 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. The decimal form is shorter and what /location/search returns; 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';

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 wrapper 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';

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 (data-endpoint + a pk_ key) 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 data-endpoint="astrology/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 heading="Your reading" 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 wrapper 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.

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 data-endpoint and a publishable-key and it renders its own form and fetches in the browser. 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 names the route that answers the submitted request and location-url names the one that answers the city search, so both halves of a birth-data form go to your server and no key of any kind reaches the browser. 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 both its requests through your server and carry no key at all. A single <link> to the practitioner theme preset 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

Components

What you can build

• Astrology dating apps with synastry charts and compatibility scores.
• Kundli matching platforms with Guna Milan and Mangal Dosha checks.
• Daily horoscope embeds for wellness, news, and lifestyle apps.
• Tarot reading apps with daily pulls, three-card spreads, and Celtic Cross.
• Numerology calculators with full-chart breakdowns and personal year forecasts.
• Biorhythm dashboards with critical-day alerts.
• I Ching apps with hexagram lookup and three-coin casting.

Theming

Every component reads from --roxy-* CSS custom properties. Override globally on :root or per element. Light + dark defaults, container queries for responsive layouts at 320px and up. The CDN bundle auto-loads these tokens, and your own declarations always win over the defaults: they are declared at zero specificity and inside the roxy cascade layer, so one plain line beats them in both modes, with no !important and no extra selector weight, and it works from inside a layer of your own. See THEMING.md for the full token reference and for the one rule a page that scopes its theme to a wrapper has to know.

:root {
	--roxy-accent: #6d28d9;
	--roxy-radius-md: 12px;
}

roxy-natal-chart {
	--roxy-accent: #ec4899;
}

Reach inside the component from your own CSS

Every chart and reading component names its structural blocks with part, so a stylesheet outside the component can restyle or hide any of them with no JavaScript and no fork. The names are the same in every component, so one rule covers the whole library.

/* Chart only. The wheel, the tables and the numbers stay; the written report goes. */
roxy-natal-chart::part(readings) {
	display: none;
}

/* A single named block. Every structural section carries `section` plus its own
   name, so the chart patterns block goes without touching anything else. */
roxy-natal-chart::part(patterns) {
	display: none;
}

/* Or restyle it. */
roxy-natal-chart::part(card) {
	border: 0;
	box-shadow: none;
}

The parts: card, header, chart, legend, details, table, tablist, tab, panel, section, readings, reading, detail (the row a list opened in place), plus form, hint, field-error, loading, error, edit-bar and attribution on the built-in states. hint is the help text under a field of the built-in form, which quotes the API reference for that field: hide it with ::part(hint) when the page is written for a reader who did not come for the reference, or with hide-sections="hint" on one element, and the label, the input and its validation stay. The copy-paste snippets carry hide-sections="hint" already. A section also carries its own name, which is what ::part(patterns) above targets, so any single block can be dropped or restyled on its own.

That list is the shared vocabulary, not the whole set. components-catalog.json carries a parts array for every component, so you can read the exact names a component answers to instead of guessing or inspecting the DOM. A name means the same block wherever it appears, which is what makes one rule enough: ::part(aspects) reaches the aspect grid on a natal chart, the aspect list on an aspects table and the transit aspects on a transits table alike.

One nesting rule worth knowing: parts reach exactly one shadow root deep, and a component that draws another one re-exports its parts, so roxy-relocation-wheel::part(readings) reaches the wheel nested inside it.