@roxyapi/ui

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
# or
bun add @roxyapi/ui

import '@roxyapi/ui';
// or per component
import '@roxyapi/ui/components/natal-chart';

React users get a typed package with the same components.

npm install @roxyapi/ui-react

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

export function Chart({ data }: { data: NatalChart }) {
	return <RoxyNatalChart data={data} />;
}

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.

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.

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, 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 is refused client-side, so the component 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), collapses optional fields under one Advanced disclosure, and reads a lang attribute for localized responses. 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.

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 | | Practitioner theme preset (one link, warm rosewater) | cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/themes/practitioner.css | | shadcn registry | npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/{name}.json | | Components catalog (JSON: every component, domain, and endpoint) | cdn.jsdelivr.net/npm/@roxyapi/ui@latest/components-catalog.json |

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-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, 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-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 | | <roxy-tarot-spread> | Tarot | POST /tarot/spreads/{three-card,celtic-cross,love}, /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 /chinese-astrology/zodiac/sign, GET /chinese-astrology/zodiac/{animals/{id},{id}/daily,compatibility/{sign1}/{sign2}} | The animal for a date, one animal in full, a daily reading, or a pair scored | | <roxy-almanac-day> | Chinese | GET /chinese-astrology/calendar/{day/{date},monthly}, POST /chinese-astrology/calendar/auspicious-days | Day officer, favours and avoids, clash animal and pillars, as one day, a month, or a date search | | <roxy-flying-star-chart> | Feng Shui | POST /feng-shui/flying-stars/natal, GET /feng-shui/flying-stars/annual/{year} | Nine-palace flying star plate with the mountain, period and water star per palace, the facing and sitting mountains and the structure | | <roxy-kua-card> | Feng Shui | POST /feng-shui/kua, POST /feng-shui/eight-mansions | Kua number and trigram over the eight-sector direction map, favourable and unfavourable sectors ranked | | <roxy-mayan-day-sign> | Mesoamerican | POST /mesoamerican-astrology/mayan/tzolkin, POST /mesoamerican-astrology/mayan/chart | Day sign and coefficient with the trecena, the reading, and the Calendar Round on the fuller response | | <roxy-vastu-mandala> | Vastu | POST /vastu/mandala, POST /vastu/entrance | Pada grid with a devata per square, the brahmasthan, and the entrance pada lit with its effect | | <roxy-biorhythm-chart> | Biorhythm | POST /biorhythm/{daily,forecast,critical-days} | Daily bars, forecast cycle lines, critical days | | <roxy-dosha-constitution> | Ayurveda | POST /ayurveda/constitution | Vata, pitta and kapha shares as one bar with the dominant humour and the cited factors behind it | | <roxy-hexagram> | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram figure with trigrams, judgment, image, and a reading per line (statement plus meaning); a cast highlights the moving lines and the resulting hexagram | | <roxy-crystal-card> | Crystals | GET /crystals/{id} | Photo, meaning sections, chakra, zodiac, element, hardness, keywords, and pairings | | <roxy-crystal-grid> | Crystals | GET /crystals, /crystals/chakra/{chakra}, /crystals/element/{element}, /crystals/zodiac/{sign}, /crystals/birthstone/{month}, /crystals/search | Crystal gallery tiles with photo, name, and colour swatches | | <roxy-dream-card> | Dreams | GET /dreams/symbols/{id} | Symbol name, interpretation body, and letter chip | | <roxy-dream-search> | Dreams | GET /dreams/symbols | Matched dream symbols as selectable tiles with a letter chip | | <roxy-angel-number-card> | Angel Numbers | GET /angel-numbers/numbers/{number} | Number meaning with spiritual, love, career, money, twin flame, biblical, and shadow sections | | <roxy-angel-number-lookup> | Angel Numbers | GET /angel-numbers/lookup | Pattern analysis plus known meaning and digit-root fallback | | <roxy-reference-card> | Reference | GET /astrology/{signs,planet-meanings}/{id}, /vedic-astrology/rashis/{id}, /iching/trigrams/{id}, /human-design/{gates,centers}/{id}, /numerology/{meanings,compound-number}/{number} | Symbol, name, description, keyword chips, and an attribute grid for any glossary lookup | | <roxy-endpoint-form> | Helper | Any endpoint, from the spec | Schema-driven form, emits roxy-submit | | <roxy-location-search> | Helper | GET /location/search | Debounced city search input, emits roxy-location-select | | <roxy-data> | Helper | Any response shape | Generic fallback renderer for unknown shapes |

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; your :root { --roxy-* } overrides always win over the defaults. See THEMING.md for the full token reference.

: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, plus form, loading, error, edit-bar and attribution on the built-in states. 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.

Chart without the written report

For the same outcome in markup rather than CSS, set hide-readings. The component renders the chart and the data and leaves the interpretation out of the page entirely, which is what you want when your own copy supplies the words.

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

<RoxyNatalChart data={chart} hideReadings />

It is off by default, so nothing changes until you ask for it. Wheels, maps, tables, grids, legends, badges and every number stay; the interpretive prose is what goes.

That line is drawn on the content, not on the block, so a block made of measurements stays even when it reads like analysis. The clearest case is the natal chart patterns block: a T-Square or a Stellium is a geometric fact about where the bodies sit, so the figure, its element and modality, its tightness and its planets all survive, and only the paragraph under them goes. To drop the block itself, use hide-sections below.

Which components it applies to

Every component that renders a written interpretation acts on it, so you never have to test a tag to find out. A pure chart or table has no interpretation to take away, so on those it is a no-op by definition and there is nothing to know.

There is exactly one component where it is a no-op despite the component being mostly prose, and that is deliberate:

| Component | Behaviour | |---|---| | <roxy-dream-card> | hide-readings is ignored. The dream symbol response is the symbol, its dictionary letter and the interpretation, so removing the interpretation would leave a heading over nothing. Style it with ::part(card) or leave the card out of the page instead. |

What each family keeps when you set it:

• Charts and wheels keep the drawing, the legend, the glyphs, every degree and house, and the tab strip.
• Tables keep every row and column, including the calculated ones (kaksha bindus, koota scores, significance bars, orbs and strengths).
• Cards keep the header, the badges, the meters and the fact grids: a dosha keeps its present or absent verdict, its phase and its severity; a crystal keeps its Mohs hardness and its attribute grid; a horoscope keeps its energy meter, its Moon placement, the transits behind the reading, its key dates, and the dated sky events the reading was built on, each with its exact instant and the house it falls in.
• Vedic responses keep the sidereal frame caption, so a chart is still reconcilable against another calculator.

What goes: interpretation paragraphs, the reading accordions, keyword chips attached to a reading, remedies and action steps and strengths lists (sentences laid out as bullets), and any section whose only content was one of those, heading included.

Remove a whole block

Every component also takes hide-sections (hideSections in React and Vue): a comma-separated list of part names, and each one named is taken off that component.

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

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

The names are the same part names listed above, so anything you can target with ::part() you can also drop with an attribute. The rule is generated from the name rather than from a list of components that opted in, so it works on every component, and a name no block carries hides nothing rather than erroring.

Use hide-readings when the words must not ship, and hide-sections when a block should not show. They are different tools rather than two spellings of one. hide-readings drops interpretive pr