Astrology UI components setup guide

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

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

Why RoxyAPI UI

Most data APIs leave you to build the visual layer yourself. Birth charts mean SVG geometry, panchang means complex tables, dasha means timelines, tarot means card layouts and reversed-card flips. We ship the finished components so you keep your time for product work.

• Stateless. You fetch with the SDK, pass the response as the data prop, the component renders. No global stores, no setup.
• Framework agnostic. React, Next.js, Vue, Svelte, Angular, Solid, vanilla HTML, WordPress. Same components everywhere.
• Themed from design tokens. A handful of --roxy-* base tokens restyle every component in light and dark, and five named presets ship as one stylesheet each. Match any brand without rebuilding the bundle.
• Charts open full size. A click on any drawn chart, or its toolbar button, opens it enlarged over the page.
• Accessible by default. WAI-ARIA roles, keyboard navigation, reduced-motion gating, axe-core verified.
• Small, and capped in CI. Under 180 KB gzipped for every domain in one file, under 33 KB per component when imported individually. Both ceilings are enforced on every release, so the numbers cannot drift upward silently.
• MIT licensed. Use it in commercial apps. No AGPL, no copyleft.

Pick your path

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

Copy-paste widgets (no code)

The same components run in a self-contained no-code mode: paste one snippet with a browser-safe publishable key and the widget asks for what the reading needs, or opens straight on a list when it needs nothing, fetches, and renders the result. Lists page on with Show more and open a picked entry in place, and a field that takes one entry by name is a search-as-you-type picker. No SDK call, no server, no build step. The walkthrough for site owners, the three delivery modes (hosted URL, iframe, script tag), platform guides, and the fix for a widget that shows an error all live on Copy-paste widgets. Every widget is styled and copied in the widget builder.

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

1. Install

npm install @roxyapi/ui-react

Building with Vue or Nuxt instead:

npm install @roxyapi/ui-vue

@roxyapi/ui-react supports React 18 and 19, and @roxyapi/ui-vue supports Vue 3.3 and later. Both cover every component and take the same data prop. On first mount they load the component code from jsDelivr, pinned to the exact @roxyapi/ui release the package was built against, so your lockfile pins what renders. Behind a strict Content-Security-Policy, allow cdn.jsdelivr.net in script-src, or copy node_modules/@roxyapi/ui/dist/cdn/ to your own origin and call ensureScriptLoaded(ROXY_UI_VERSION, '/assets/roxy-ui') once at app entry (both exported by the React and Vue packages).

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

2. Set your API key

In .env.local at the project root:

ROXY_API_KEY=your_api_key_here

Get your API key. Server-side use only.

3. Fetch and render in a Server Component

Every component in @roxyapi/ui-react ships with 'use client' inside, so a Next.js App Router Server Component fetches with your secret key and renders the component directly. No client file of your own, and the key never reaches the browser.

app/page.tsx:

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

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

export default async function Page() {
  const { data, error } = await roxy.astrology.generateNatalChart({
    body: {
      date: '1990-01-15',
      time: '14:30:00',
      latitude: 40.7128,
      longitude: -74.006,
      timezone: -5,
    },
  });
  if (error) throw error;

  return (
    <main>
      <h1>My astrology app</h1>
      <RoxyNatalChart data={data} />
    </main>
  );
}

Add 'use client' only to a file of your own that holds state or passes an event handler such as onRoxyLocationSelect. Every response type is exported from the component package (import type { NatalChartResponse } from '@roxyapi/ui-react'), so you never declare your own interface and never install a second package just for types.

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

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

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

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

In Nuxt, render them in any page or component, server rendered or not: the markup renders on the server and the element hydrates in the browser, with no <ClientOnly> needed. You do not need compilerOptions.isCustomElement.

4. Run

npm run dev

Open http://localhost:3000. The natal chart renders.

Path B: Plain HTML (zero build step)

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

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My astrology page</title>
  <script
    src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"
    crossorigin="anonymous"
    defer
  ></script>
</head>
<body>
  <roxy-natal-chart id="chart"></roxy-natal-chart>

  <script type="module">
    import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
    const roxy = createRoxy('YOUR_PUBLISHABLE_KEY');
    const { data, error } = await roxy.astrology.generateNatalChart({
      body: {
        date: '1990-01-15',
        time: '14:30:00',
        latitude: 40.7128,
        longitude: -74.006,
        timezone: -5,
      },
    });
    if (error) throw error;
    document.getElementById('chart').data = data;
  </script>
</body>
</html>

Open the file in any browser. The natal chart renders. Same pattern works in WordPress shortcodes, Shopify themes, Stan Store, Linktree, Notion, Bubble, Wix, Squarespace, or any builder that accepts custom HTML.

Pin the version in production

Snippets on this site load @latest. In production, pin the major version: @1 picks up every fix and never a breaking change. Pin an exact release such as @1.1.1 when you want byte-stable cache hits.

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

Serve everything from your own domain

Keep every request on your own domain and your secret key on your server. One attribute routes a widget through you: submit-url names the route that answers every request it makes, the reading and the city search alike, and no key of any kind reaches the browser.

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

The widget POSTs { path, method, body, query } to submit-url. Your route calls https://roxyapi.com/api/v2{path} with your secret key and returns the JSON unchanged:

// POST /roxy/proxy
export async function POST(request) {
  const { path, method, body, query } = await request.json();
  const url = new URL(`https://roxyapi.com/api/v2${path}`);
  for (const [k, v] of Object.entries(query ?? {})) if (v != null) url.searchParams.set(k, v);
  const res = await fetch(url, {
    method,
    headers: { 'X-API-Key': process.env.ROXY_API_KEY, 'Content-Type': 'application/json' },
    body: method === 'GET' ? undefined : JSON.stringify(body),
  });
  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
}

The city search arrives the same way, as { "path": "/location/search", "method": "GET", "query": { "q": "...", "limit": 8 } }. To answer it on a separate route, add location-url: that route receives a GET with q and limit. Allow only the paths your page uses, so the route answers your widgets and nothing else.

To serve the script files too, download roxyapi-ui-{version}.tgz from the latest GitHub release (or take dist from the npm package, every file browsable in the current dist/cdn folder), and copy package/dist/cdn and package/dist/schemas to your server side by side, as they ship. Forms read their schemas from beside the script, and the language files sit in cdn/locales/.

On a PHP site, one open source file does all of this with no code to write: Self-Hosted Widgets for PHP keeps the widget files current on your server and relays every reading and city search with a publishable key locked to your domain.

Path C: shadcn registry (Next.js + Tailwind)

Already running shadcn? Install per-component. Each entry drops a typed React component file into components/roxy-ui/{name}.tsx and merges the CSS variable theme bridge into your globals.css so your existing shadcn theme drives RoxyAPI components automatically.

npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/natal-chart.json

Use it like any other component:

import { RoxyNatalChart } from '@/components/roxy-ui/natal-chart';

export default async function Page() {
  const data = await fetchNatalChartFromYourServer();
  return <RoxyNatalChart data={data} />;
}

The component file is yours. Open it and customize freely.

What you can render

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

These are the most used. Every component, with its endpoints, attributes, and part names, is in the machine-readable components catalog.

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

Languages and localization

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

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

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

That is why the code from the widget builder and the component catalog carries no lang by default. Paste one onto a Spanish page and it renders in Spanish. Set lang yourself only when you want to fix the language regardless of the page, for example an English reading on an otherwise German site.

Load the labels for your language

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

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

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

In a bundled app, import it instead:

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

The widget builder, under Content, and the component catalog both have a language selector. Pick a language there and the snippet you copy already carries the right line.

Hosted embeds

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

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

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

What is translated, and what is not

Being straight about this saves you a support ticket:

• Readings and interpretations follow the language on every endpoint. So do the planet, sign, aspect, and house names that come back with them.
• On-screen labels follow it in German, Spanish, French, Hindi, Portuguese, Russian, and Turkish, once the label file for that language is loaded. A card reads its own labels fully in your language or fully in English, never a mixture, so a page is never blank or half-rendered.
• Column headings on the generic data tables follow it too, for every field name the API publishes a translation for. A name without one reads in plain English, and the values inside the columns follow the language either way.
• The visitor-facing form a widget draws for itself follows the language too, including its field labels and its dropdown options, so a Spanish page collects Fecha de nacimiento rather than Birth date. On a non-English page the form leaves out the English reference help text rather than mix languages.
• Fixing a language turns the page inheritance off. A component with an explicit lang ignores the page it sits on, which is the point, but it also means a later site-wide language change will not reach it.
• A regional tag works. es-AR uses the Spanish labels and Argentinian date and number formatting. A language RoxyAPI does not cover falls back to English rather than failing.

Theming

Every component takes every colour, size, space, radius, and font from a --roxy-* design token. Custom properties cross the Shadow DOM boundary, so a value set on :root reaches every component below it. Only a few tokens are bases, and everything else derives from them, so a handful of lines restyle the whole library:

:root {
  --roxy-bg: #ffffff;
  --roxy-fg: #0a0a0a;
  --roxy-accent: #4a6297;
  --roxy-font-sans: 'Inter', system-ui;
  --roxy-radius: 6px;
}

[data-theme="dark"] {
  --roxy-bg: #0a0a0a;
  --roxy-fg: #fafafa;
  --roxy-accent: #92aade;
}

--roxy-bg is the page colour and --roxy-fg the ink: the card, the secondary ink, the muted text, and every hairline derive from those two, so a warm or brand palette carries through without setting them one by one. --roxy-accent moves every accent mark and the focus ring, --roxy-radius every corner. --roxy-font-sans is unset by default, so components inherit your page font until you set it. The card is flat on the page by default; set --roxy-surface only to lift it off.

Dark mode needs no wiring. Components follow the system preference, a .dark class, or data-theme="dark" on the document, any ancestor, or the element itself. If your theme lives on a container element instead of <html>, put data-theme="light" or data-theme="dark" on that same element so every token you did not set follows your mode, not the visitor operating system.

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

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

Every derived token can still be set directly, and your value wins. To make a component read as part of your page rather than a card dropped onto it, bridge the bases to the tokens you already have: hold references (--roxy-bg: var(--background)), declare them once so your dark block moves them with everything else, and include the font and radius tokens so type and corners match too. Two open source templates ship that bridge in full, with a test that keeps it honest: the AI chatbot on a dark theme and the AI companion on a light and dark pair. The full reference, with the light and dark default for every token and what each one paints, is THEMING.md in the component repo. It is maintained alongside the components, so it never lags a release; the literal defaults ship in the package as tokens.css. It also carries ready-made patterns for dark mode, high contrast, per-domain accents, and a Tailwind token map.

The live preview at roxyapi.github.io/ui has a Theme menu that applies any preset and a Customize colors dialog, a picker per colour token that outputs a CSS block you paste into your project.

Named presets

Each preset is one optional stylesheet with a light and a dark palette that restyles every component on the page. Link one after the component script:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@roxyapi/ui@1/dist/styles/themes/practitioner.css">

All five sit in dist/styles/themes/, and the themes list in the components catalog names each one. Your own --roxy-* declarations still win over a preset.

Chart size

Every drawn chart (a wheel, a kundli, a bodygraph, a compass, a mandala) opens enlarged from its toolbar or with a mouse click on the drawing. Two tokens size them: --roxy-chart-max-width caps the chart inside its card, on :root for every chart or on one element, and --roxy-chart-expanded-width sets the width of the enlarged view (60rem by default).

Already on shadcn?

Path C installs a thin bridge that maps your existing shadcn --card, --background, --foreground, --muted-foreground, --primary, --border, --destructive, and --radius onto the RoxyAPI tokens. Your shadcn theme drives RoxyAPI components automatically. Path A and Path B users can ship the core of the same bridge as a small CSS file:

@layer base {
  :root {
    --roxy-bg: var(--background, #ffffff);
    --roxy-fg: var(--foreground, #0a0a0a);
    --roxy-surface: var(--card, var(--roxy-bg));
    --roxy-muted: var(--muted-foreground, color-mix(in oklab, var(--roxy-fg) 60%, var(--roxy-bg)));
    --roxy-border: var(--border, color-mix(in oklab, var(--roxy-fg) 14%, var(--roxy-bg)));
    --roxy-accent: var(--primary, #4a6297);
    --roxy-danger: var(--destructive, #dc2626);
    --roxy-radius: var(--radius, 6px);
  }
}

Choosing what a component renders

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

Target any block with ::part()

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

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

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

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

hide-readings: keep the chart, drop the words

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

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

<RoxyNatalChart data={chart} hideReadings />

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

hide-sections: remove a whole block

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

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

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

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

On a hosted embed

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

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

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

attribution: the credit line is yours to switch on

No component draws a RoxyAPI credit unless you ask for one, so a page renders under your brand alone. To name your source, a small "Spiritual data by RoxyAPI" link appears under a reading a component fetched for itself, in the language of the page:

<roxy-natal-chart publishable-key="pk_live_YOUR_KEY" attribution></roxy-natal-chart>
<div data-roxy-widget="natal-chart" data-publishable-key="pk_live_YOUR_KEY" data-attribution="on"></div>

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

A component you pass data to never draws it, and ::part(attribution) styles it where it does appear.

Wiring custom events

Some components dispatch typed events: roxy-submit, roxy-location-select, roxy-validation-error, roxy-render-error, and roxy-spec-error. The React package types them as handler props, such as onRoxyLocationSelect.

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

<RoxyLocationSearch
  onRoxyLocationSelect={(e) => {
    console.log(e.detail.latitude, e.detail.longitude, e.detail.timezone);
  }}
/>

In vanilla HTML, listen the standard way:

<roxy-location-search id="search"></roxy-location-search>
<script>
  document.getElementById('search').addEventListener('roxy-location-select', (e) => {
    console.log(e.detail.latitude, e.detail.longitude, e.detail.timezone);
  });
</script>

Render an AI tool result as a component

The full walkthrough, for the Vercel AI SDK and for the Anthropic, OpenAI, and Gemini connectors, is the AI astrology charts in chat tutorial. This section is the short version.

The model never calls a widget. It calls a RoxyAPI tool over Remote MCP exactly as it does today, and the tool result comes back into your app as a message part: the tool name the model used plus the JSON string the tool returned. Your interface, not the model, maps that name to a component and sets data. So the model needs no component names, no list of which tools have a chart, and no UI instructions in its prompt; the same JSON these components already take is what arrives, which is why they double as generative UI for AI chat. Four lines put it on screen:

1. Find the tool name and the result text in whatever your chat framework or model API hands you.
2. JSON.parse the text.
3. componentForTool(name) for the component.
4. Set data.

componentForTool is exported from @roxyapi/ui, @roxyapi/ui-react, and @roxyapi/ui-vue, and returns { tag, pascal, attrs, operationId, toolName }, or undefined for a tool no component covers, so a reference lookup keeps answering in prose instead of breaking.

'use client';

import * as RoxyUI from '@roxyapi/ui-react';
import type { ElementType } from 'react';

export function ToolWidget({ toolName, resultText }: { toolName: string; resultText: string }) {
  const binding = RoxyUI.componentForTool(toolName);
  if (!binding) return null;

  const Widget = RoxyUI[binding.pascal as keyof typeof RoxyUI] as ElementType;
  return <Widget data={JSON.parse(resultText)} {...binding.attrs} />;
}

The same thing in plain HTML, with the CDN bundle:

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js" defer></script>
<script>
  function renderToolResult(toolName, resultText) {
    const binding = RoxyUI.componentForTool(toolName);
    if (!binding) return;

    const el = document.createElement(binding.tag);
    el.data = JSON.parse(resultText);
    document.body.append(el);
  }
</script>

The compact response shape is decoded inside the component, so leave it on and pass the result straight through. expandCompact is exported from the same three packages when your own code wants the plain object.

Any chat UI where you control the markup for a tool result can host these components: the Vercel AI SDK and AI Elements, assistant-ui, CopilotKit, or a hand-rolled one. OpenAI ChatKit is the exception, because its widgets are a closed declarative schema of cards and fixed nodes with no slot for a custom component. The open source chatbot template is the worked example: one file maps the message parts, one file renders them.

Common gotchas

const response = await roxy.astrology.generateNatalChart({...});
element.data = response;

const { data, error } = await roxy.astrology.generateNatalChart({...});
if (error) throw error;
element.data = data;

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

Verification checklist

After integrating, confirm:

• No [object Object] strings in any chart, table, or card.
• No "Loading..." that never resolves.
• Browser console has no errors and no warnings.
• Dark mode flips when you toggle [data-theme="dark"] on <html>.
• Production build (npm run build) compiles without errors.
• The key in any client-bundled code is a publishable key, not a secret one.

Where to go next

• Live customizer at roxyapi.github.io/ui. Theme presets, colour pickers, copy-paste integration snippets, every component rendered against real responses.
• GitHub at github.com/RoxyAPI/ui. MIT licensed. Release notes, runnable examples, and issues.
• Catalog page at roxyapi.com/ui for distribution surfaces and FAQ.
• SDK reference at /docs/sdk for every endpoint method.
• Get your API key. Instant delivery, no approval queue.

Frequently asked questions