> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centaur.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget reference

> Options, methods, callbacks, and runtime behavior of the widget SDK.

> [!NOTE]
>
> Widgets are in early access. Sample mode is open to everyone. Live mode is enabled for approved partners in stages.

New to widgets? Start with [Embed a widget](/integrations/widgets.md).

## Options

Your snippet owns these settings. To change an installed widget, change its code.

| Option | Supported values |
| - | - |
| `kind` | `feed` or `positioning` |
| `mode` | `sample` or `live`, always explicit |
| `widgetId` | Your public widget ID. Live mode only. |
| Feed `selection` | Optional `assetIds` and `traderIds`, each with 1–20 positive IDs |
| Feed `selection.assetClass` | Optional array of 1–5 values: `crypto`, `stocks`, `indices`, `commodities`, `fx` |
| Feed `selection.assetChoices`, `traderChoices` | Optional `{ id, label }` arrays that let visitors pick from your configured IDs |
| Positioning `selection` | Exactly one `assetId` |
| `appearance.theme` | `light`, `dark`, or `system` |
| `appearance.width` | Integer 200–1600 pixels, or a string from `1%` to `100%` |
| Feed `appearance.height` | Integer 240–1200 pixels. Positioning uses its natural height. |
| Feed `assetUrls` | Map of asset ID to a URL in your product |
| Positioning `viewActivityUrl` | URL in your product for the asset's activity |

Give every configured ID a label. Visitors can narrow your list, not widen it. For the general feed, omit `selection` filters. An empty array is invalid.

Look up asset and trader IDs with [Find IDs](/integrations/find-ids.md). Do the lookup on your server: it needs an API key, and the widget needs only its widget ID. Sample IDs such as `900001` do not work in live mode.

## Filter by asset class

> [!NOTE]
>
> The `assetClass` filter is not available in production yet. Do not rely on it until this note is removed.

Set `selection: { assetClass: ['crypto'] }` to show only crypto activity. Several classes match any of them. Omit `assetClass` for all classes. Empty or unknown values are invalid. `stocks` excludes assets classified as indices, as in the Centaur app.

Filters combine, so `stocks` with a Bitcoin selection returns an empty feed. Centaur filters first, then shows the latest 20 posts. Visitor choices stay inside your configured classes.

## Methods

`CentaurWidgets.v1.mount(container, options)` renders a widget and returns a handle. Mount once per container and give each container a unique ID. Several widgets can share one SDK script. `CentaurWidgets.v1.version` identifies the loaded release.

`handle.update(patch)` changes `selection`, `appearance`, `assetUrls`, `viewActivityUrl`, or callbacks. Each one replaces its previous value, so pass the complete selection or appearance you want to keep. When you change a positioning widget's asset, pass its `viewActivityUrl` too: changing the asset clears the old one. To change `kind`, `mode`, or `widgetId`, destroy the widget and mount a new one.

`handle.destroy()` removes the widget and stops its requests. Call it when your app removes the container or navigates away.

[Widget recipes](/integrations/widget-recipes.md) show each method in working code.

## Callbacks

Add these optional functions to your options:

| Callback | Called when |
| - | - |
| `onReady` | The first data load succeeds. |
| `onSelectionChange` | The selection changes, through a visitor's choice or `update`. |
| `onError` | A request or the configuration fails. The error has a category, a code, whether it is retryable, and a request ID when available. |
| `onAssetNavigate` | A visitor clicks an asset link. Receives `{ assetId, url }`. |

`onAssetNavigate` handles the click unless it returns `false`. Cmd-click and other modified clicks always open the link normally.

`assetUrls` and `viewActivityUrl` accept HTTP, HTTPS, or relative URLs.

## Runtime behavior

* Visible live widgets aim to refresh about every 30 seconds. This is a target, not an SLA. Hidden widgets pause.
* New posts wait until the visitor selects the new-posts button.
* A temporary failure keeps the content already shown. An access denial clears it.
* If the widget's stylesheet cannot load, it asks the visitor to reload the page and reports `STYLESHEET_FAILED` through `onError`. Reloading fetches the current SDK; remounting alone does not. If the error persists, check the network and your [Content Security Policy](/integrations/widgets.md#content-security-policy).
* Source links and the required Centaur attribution open in a new tab. The feed shows photos in order, with no enlarged viewer. Videos do not play yet.
* The SDK runs in your page. Shadow DOM isolates its styles, not its code.
* `/v1/sdk.js` updates in place on the next page load. Breaking changes ship as `/v2/`.

## What the positioning card shows

The card covers positions Centaur tracks, not the whole market.

* Long and short position counts.
* Up to five open positions from the traders with the largest audiences: side, entry price, and return from entry to the latest recorded price. Other traders count toward the totals but are not listed.
* **Latest moves**: the three most recent trades on the asset in the last seven days.

Missing prices and returns show as "—".


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.