`. The script mounts the matching component from a generated slug map: with every path parameter supplied as a `data-*` attribute (`data-sign`, `data-id`) it fetches on mount, otherwise it renders the same input form. A second `data-*` attribute picks a variant (`data-period`, `data-mode`, `data-type`, `data-spread`). To keep every key on your own server instead, drop the publishable key and give the tag `data-submit-url` and `data-location-url`: the widget renders the form and routes both its requests there. `data-submit-context` rides along with the submitted one. **Theme every widget in one link.** Add `` for a warm rosewater serif look, or set the `--roxy-font-display` token alone to swap result headings to a display face (it defaults to the body font, so nothing changes until you set it). See [THEMING.md](packages/ui/THEMING.md). ### Pattern 5: MCP tool-call response A Remote MCP server at `roxyapi.com/mcp/{domain}` exposes each RoxyAPI endpoint as a tool, named for its method and path: `post_astrology_natal_chart`, `post_tarot_spreads_three_card`, `get_tarot_cards_id`. When your model calls one, the result is a single text content block holding the JSON string, and that JSON is the same shape the SDK returns. So the whole render is: parse it, look up the component, set `data`. `componentForTool(name)` is the lookup, exported from `@roxyapi/ui`, `@roxyapi/ui-react` and `@roxyapi/ui-vue`, and from the `/tool-component` subpath of each for a module that decides which component to render without rendering one (a server component, a route handler, a worker): `import { componentForTool } from '@roxyapi/ui-react/tool-component'` carries the lookup, `expandCompact` and the name table, and no elements. It returns `{ tag, pascal, attrs?, operationId, toolName }` for a tool the library draws, and `undefined` for one it does not. `operationId` names the OpenAPI operation the tool calls, for your logs or for finding the endpoint in the API reference. `attrs` values are always strings: set them as attributes in the DOM, spread them as props in React and Vue. ```ts import { componentForTool } from '@roxyapi/ui'; // `toolName` and `result` are what your model handed back for one tool call. 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: ```tsx 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 ; } ``` Three things the lookup already handles, so you do not have to: - **A compact result.** Ask a tool for the compact shape and its same-shaped arrays arrive columnar, as `{ "__cols": [names], "__rows": [[values]] }`. Every component decodes that on the way in and renders the same card either way. `expandCompact(value)` is exported too, for the paths that read the JSON before an element does. - **A server-prefixed name.** Some hosts prefix the tool name with the server it came from and a colon (`roxy_tarot:post_tarot_daily`). The lookup strips the prefix. - **Which component leads.** Three responses are rendered by two components each, and the lookup returns the one that leads with the drawing: - the natal chart response is drawn by both `` and ``, the lookup returns `` - the transit aspects response is drawn by both `` and ``, the lookup returns `` - the Vedic birth chart response is drawn by both `` and ``, the lookup returns `` Full recipe, including the vendor connectors and the Vercel AI SDK: . No field renames. No glue code. Use the decision tree above to pick the component for any tool the lookup does not cover. ### Pattern 6: Next.js RSC streaming Server fetches with the secret key, client renders with the React component. The API key never crosses the network. ```tsx // app/page.tsx (Server Component) import { createRoxy } from '@roxyapi/sdk'; import BirthChartView from './birth-chart-view'; const roxy = createRoxy(process.env.ROXY_API_KEY!); export default async function Page() { const { data } = await roxy.vedicAstrology.generateBirthChart({ body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 }, }); return ; } ``` ```tsx // app/birth-chart-view.tsx (Client Component) 'use client'; import { RoxyVedicKundli } from '@roxyapi/ui-react'; export default function BirthChartView({ data }: { data: unknown }) { return ; } ``` ### Pattern 7: server-rendered markup (WordPress, JSX SSR, static HTML) When the page is rendered on the server or served from cache, there may be no JavaScript to set the `data` property per element. Render the response into a child `` element) and `serializeRoxyData(data)` (returns just the escaped JSON string). They escape `<`, `>`, and `&` so a string field containing `` cannot break out of the block. A raw `JSON.stringify` of a response with interpretation prose can contain `` and corrupt the page or open an injection hole. ```ts import { roxyDataScript } from '@roxyapi/ui'; const { data } = await roxy.astrology.generateNatalChart({ body }); const html = `${roxyDataScript(data)}`; ``` The emitted markup: ```html ``` Rules for this pattern: - The JSON must be the unwrapped RoxyAPI response, the same shape you would assign to `element.data`. Do not embed the SDK envelope (`{ data, error, request, response }`); embed `data`. - The script must be a direct child of the component and carry both `type="application/json"` and `class="roxy-data"`. `roxyDataScript` emits both. - The JavaScript property always wins. If you assign `element.data` in script, the markup is ignored. One component covers both server-rendered and dynamic pages with no branching. - You can nest a server-rendered HTML fallback inside the same element for no-JavaScript and crawler views. The component reads only the marked script and leaves the fallback in place. - In a language that cannot call the TS helper (PHP, Python, Go), mirror its rule exactly: escape `<`, `>`, and `&` to their `\u003c`, `\u003e`, `\u0026` JSON escapes. The WordPress example does this in PHP. This is how the WordPress plugin renders: PHP fetches the response server-side, caches it, and writes the script into the page. The same shape works in any framework that emits HTML. - Writing the tag itself in a React or Next.js file? Import `@roxyapi/ui-react/jsx` once anywhere in the project and every `roxy-*` tag is typed, with its attributes and their legal values. It is the raw-tag path, so it carries attributes only; a page that passes a response uses the wrapper component instead, which sets `data` as a property. ## Localized responses Most RoxyAPI endpoints return their interpretation text in the language you ask for, selected with the `lang` query parameter (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`, `zh-Hans`, `zh-Hant`). Human Design, for example, returns the type, strategy, authority, profile, channel, center, gate, and line readings in the requested language. Coverage varies by domain, and a field with no translation in the language you asked for comes back in English. Chinese is named by script rather than by language, so `zh-Hant` and `zh-Hans` are the two values to send. A component resolves a regional tag for you: `zh-TW` and `zh-HK` read as traditional, `zh-CN` and `zh-SG` as simplified. The components hold no copy of their own; they print the prose the response carries. So the language of the response is the language of the render. ```ts const { data } = await roxy.humanDesign.generateBodygraph({ body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 }, query: { lang: 'de' }, }); ``` `lang` is a query parameter even on a POST endpoint. Put it in `query`, never in `body`; a `lang` key in the body is ignored and you get English back. In the self-fetch pattern you do not fill a language field: the component reads the page language and routes it to the `?lang=` query on submit. ## The labels the components write Separate from the response, and set separately. The wording a component supplies itself (headings, tab labels, table captions, legends, empty states) comes from a catalogue you load for the language you serve. ```html ... ``` ```ts import '@roxyapi/ui'; import '@roxyapi/ui/locales/es'; ``` The language comes from `lang` on the element, else the nearest ancestor carrying `lang`, else ``. So a site that already declares its language needs no per-component attribute. A regional tag reads its base language, so `es-AR` and `es-419` both use `es`, and the request goes out as `?lang=es` because that is what the API accepts. English is the default and needs no catalogue. Load only the languages your site serves; one catalogue covers every Roxy component on the page. A catalogue ships for every language the API serves: `de`, `es`, `fr`, `hi`, `pt`, `ru`, `tr`. Coverage grows card by card, and a card is either translated or it is not, so a component reads its own labels in your language or writes them in English, never a mixture. Every term is sourced from named astrology references in that language rather than translated word for word. **The values the API returns are never rewritten**: a planet, sign, aspect or house-system name renders exactly as the response carries it, so the words on the chart and the words in the response can never disagree. Ask for a language and the response carries the reader-facing name beside the English one, so the chart prints the translated name while the English one stays available to compare against in your own code. Dates, times and numbers need no catalogue at all. They follow the same page language and are written the way that language writes them, hour cycle included, so a German page reads `15. Jan. 1990, 14:30` and an Argentine one `15 de ene de 1990, 2:30 p. m.`. Ask for the response language AND load the matching catalogue, and the whole card reads in one language. ## Theming and dark mode Components react to three signals in priority order. No events to dispatch. No JS bridge to write. The CDN bundle (`dist/cdn/roxy-ui.js`) auto-loads the design tokens, so a single script tag yields full theming and dark mode with nothing else to add. The npm and React paths inherit the same tokens through the components; only set up `tokens.css` yourself if you import per component without the full bundle. | Signal | Where | Effect | |---|---|---| | `prefers-color-scheme: dark` | OS | Default. Follows user system setting. | | `data-theme="light"` or `data-theme="dark"` | `` / `` / any ancestor / the component itself | Wins over OS. Per-element override scope works. | | `.dark` class | The component itself or any ancestor (typically ``) | Same effect as `data-theme="dark"`. Use when the host stack already ships a `.dark` toggle (Tailwind, shadcn). | To toggle at runtime: ```ts document.documentElement.dataset.theme = 'dark'; // or 'light' ``` That single line re-themes every Roxy UI component on the page. Persist user choice in `localStorage` from your own code; the library does not own preferences. Per-element scope is supported: ```html ``` Every visible aspect of the chart is driven by `--roxy-*` CSS custom properties on `:host`. Override any token on `:root`, on `:host`, or per element. Do not write Tailwind utility classes inside the components; the Shadow DOM boundary stops them at the door. **One plain declaration is the whole override, including from inside a layer of your own.** The shipped defaults are declared at zero specificity and inside the `roxy` cascade layer, so `:root { --roxy-accent: #6d28d9 }` beats them in both modes, and so does the same line inside `@layer base`, which is where a framework maps its palette onto ours. Never reach for `html:root` or `!important`. If you link `tokens.css` after your own CSS, name the order once with `@layer roxy, base, components, utilities;`. And if your tokens are scoped to a wrapper rather than to `:root`, write the mode on that same wrapper (`data-theme="light"` or `"dark"`), because every token you did not override is still decided at the document root by the visitor OS. ## Choosing what a component renders Three tools, one vocabulary. Every structural block carries a `part` name; `::part()` targets it from a stylesheet, `hide-sections` drops it on one element, and `hide-readings` removes interpretive prose from the markup entirely. **Pick by what you need:** | Need | Use | |---|---| | Restyle a block | `::part(name)` in your CSS | | Hide a block everywhere on the site | `::part(name) { display: none }` | | Hide a block on ONE element, keep it on another | `hide-sections="name"` | | Keep the chart, drop the written interpretation | `hide-readings` | `hide-readings` and `hide-sections` are different tools, not two spellings of one. `hide-readings` leaves the prose out of the markup, so the page never ships text it is not displaying. `hide-sections` hides the block whatever it holds, because a block may be measurements you have no reason to strip. ```html ``` ```tsx ``` Both are off by default. `hide-sections` takes a comma-separated list, is case-insensitive, ignores spaces around commas, and a name the component does not carry hides nothing and is not an error, so one list can be applied across a page of mixed components. **The line `hide-readings` draws is on the CONTENT, never on the block**, so a block that reads like analysis stays when it is made of measurements. `` and `` both render the `patterns` payload and both make the same cut: figure name, element, modality, tightness and planet chips are geometry and survive; the paragraph under them is the reading and goes. To remove the block itself, that is what `hide-sections` is for. What survives elsewhere: charts keep the drawing, legend, glyphs, degrees and tab strip; tables keep every calculated column (kaksha bindus, koota scores, orbs, strengths); cards keep header, badges, meters and fact grids; every Vedic response keeps its sidereal frame caption. One documented no-op: `` ignores `hide-readings`, because the response IS the interpretation and removing it would leave a heading over nothing. ### The part vocabulary | part | What it names | |---|---| | `card` | The component's own card or wrapper root | | `header` | The heading row (title, meta, score) | | `chart` | The graphic: wheel, map, bodygraph, bar set, hexagram figure, card art | | `legend` | The key to the chart | | `details` | The numeric summary: pills, badges, stat lists, fact tiles | | `table` | A data table, or the scroll box around one | | `tablist`, `tab`, `panel` | The view switch and the panel it governs | | `section` | Any structural block, paired with a specific name (`section patterns`), so `::part(patterns)` targets that block alone | | `readings` | The interpretation accordion | | `reading` | One disclosure card inside it | | `hint` | The help text under a field of the built-in form, which quotes the API reference for that field. Hide it with `::part(hint)` on a page written for a reader who did not come for the reference; the label, the input and the validation stay | | `field-error` | One message the API returned about one input of the built-in form, printed under it, or about one record card, printed on it | | `detail` | The row a list opened in place under its tiles (dream search, crystal grid); the card inside is themed through the tokens | | `form`, `loading`, `error`, `edit-bar`, `attribution` | The built-in states, on every component | That table is the shared vocabulary, not the whole list. **`components-catalog.json` carries a `parts` array for every component, so 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. Parts reach exactly one shadow root deep, and a component that draws another re-exports its parts, so `roxy-relocation-wheel::part(readings)` reaches the wheel it nests. ## Rules every agent must follow - Always call `/location/search` first before any chart endpoint that takes latitude, longitude, or timezone. Use `` for the input UI. - Pass the response object directly. Components are stateless; they do not fetch internally except for ``, ``, and the widgets auto-mount script. - Use the typed SDK from `@roxyapi/sdk` so prop shapes match the spec automatically. - Theming is CSS custom properties on `:root` or per element. Switch light and dark via `data-theme` on any ancestor (see the table above). Do not write Tailwind classes inside the components; the shadow DOM ignores them. - Honor reduced motion. The library already respects `prefers-reduced-motion: reduce` and the `--roxy-motion-duration` variable. - A11y violations are CI failures. Do not paste over `role` or `aria-*` attributes; the components emit them correctly already. - Component types come from the OpenAPI spec via `@hey-api/openapi-ts`. Do not redefine response shapes locally; if a field is missing, fix the spec, regenerate, propagate. ## Domain ordering When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, forecast, human design, Chinese astrology, feng shui, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers. Sort by this list and skip any domain the catalog does not carry a component for. Location is utility, not a selling domain. The `domain` field in `components-catalog.json` carries the same names, so sort by this list rather than by whatever order you discovered components in. ## What not to ship - Do not bundle `@roxyapi/ui` with `@roxyapi/ui-react` or `@roxyapi/ui-vue`; they ship independently. - Use `@roxyapi/ui-react` for React projects and `@roxyapi/ui-vue` for Vue and Nuxt projects. Use `@roxyapi/ui` directly elsewhere. - Do not write your own kundli component. The lifted layout in `` is the canonical RoxyAPI render path. - Do not call astrology endpoints with hardcoded coordinates. Always geocode first via `` or `roxy.location.searchCities()`. - Do not declare a local `interface XyzData` to describe a RoxyAPI response. Import the type from the component package you already installed: `import type { XyzResponse } from '@roxyapi/ui-react'` (or `@roxyapi/ui-vue`, or `@roxyapi/ui`). Local interfaces drift the moment the spec changes. You do not need `@roxyapi/sdk` for types. - Do not write Tailwind utility classes inside a component. The Shadow DOM boundary stops them at the door. Theme through `--roxy-*` CSS custom properties on `:root` or per element instead. - Two ways to feed a component, no third. Controlled (default, recommended for production): pass `data` as a prop or hydrate from a child `roxy-data` JSON island; your server holds the secret key. Self-fetch (no backend): set `data-endpoint` + a `pk_` `publishable-key` and the component renders its own form and fetches in the browser (a secret key is refused client-side). Do not wrap a component in your own fetch loop or call a chart/table/card's internals. - Do not redefine theme tokens or invent your own naming. Override the existing `--roxy-*` custom properties; the full list is in `THEMING.md`. ## Where to look next - **Machine-readable catalog, and the one to reach for first**: . Every component with its `tag`, `pascal` name, `domain`, what it renders, the `endpoints` it consumes, its `parts`, and copy-paste `snippets`. Fetch and query it instead of scraping the tables in this file. - Token reference: `THEMING.md`, beside this file in the package - Endpoint reference: - Integration guide: - Live preview of every component: