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

# Usage

> How to embed a Cesto widget on your page. One URL, one iframe tag, and the width is yours.

This page is everything you need to embed a widget on your page. The whole integration is one URL inside an `<iframe>` tag. There is no JavaScript to install and no events to listen for. Pick a widget, point it at a basket, choose a width, and you are done.

## The URL

```
https://widget.cesto.co/<widget-name>?basket=<slug>
```

`<widget-name>` is one of `hero-card`, `performance`, `overview`, or `pill-row`. `<slug>` is the basket's slug, which is the same value used in `app.cesto.co/product/<slug>`.

## The four widgets

| Widget      | `<widget-name>` | Aspect ratio | Min width |
| ----------- | --------------- | ------------ | --------- |
| Hero card   | `hero-card`     | 5 : 4        | 360 px    |
| Performance | `performance`   | 15 : 8       | 540 px    |
| Overview    | `overview`      | 2 : 1        | 480 px    |
| Pill row    | `pill-row`      | 15 : 2       | 300 px    |

Aspect ratio is the recommended shape. Min width is the floor below which the widget starts shedding affordances (the Invest text collapses to an arrow, allocation pills hide, and so on). The widget still paints below that floor, it just simplifies.

## Embed snippet

Drop this into any HTML page. Replace `hero-card` and `ai-leaders-portfolio` with the widget and basket slug you want.

```html theme={null}
<iframe
  src="https://widget.cesto.co/hero-card?basket=ai-leaders-portfolio"
  style="width: 100%; aspect-ratio: 5 / 4; border: 0;"
  loading="lazy"
  title="AI Leaders basket"
></iframe>
```

That is the entire integration. The widget fetches its own data, renders the basket, and opens `app.cesto.co/product/<slug>` in a new tab when the user taps Invest.

## Finding a basket slug

Every basket on `app.cesto.co` has a slug in its URL. Open the basket on the website and copy the last path segment, which is the slug:

```
https://app.cesto.co/product/ai-leaders-portfolio
```

In the URL above, the slug is the final segment: `ai-leaders-portfolio`. You can also discover slugs programmatically through the Cesto API at `GET /products`.

## Sizing

The widget's interior uses CSS container queries, so it scales proportionally with whatever pixel width its parent column gives it. The recommended pattern is `width: 100%` plus `aspect-ratio`, letting the page decide width and letting the aspect ratio decide height.

<CodeGroup>
  ```html Responsive (recommended) theme={null}
  <iframe
    src="https://widget.cesto.co/performance?basket=ai-leaders-portfolio"
    style="width: 100%; aspect-ratio: 15 / 8; border: 0;"
    loading="lazy"
  ></iframe>
  ```

  ```html Fixed pixel size theme={null}
  <iframe
    src="https://widget.cesto.co/performance?basket=ai-leaders-portfolio"
    width="900"
    height="480"
    style="border: 0;"
    loading="lazy"
  ></iframe>
  ```
</CodeGroup>

A few tips:

* Keep `width: 100%` whenever possible and let the host column drive the width. The widget will reflow itself.
* Use `loading="lazy"` for widgets below the fold so the iframe defers until it scrolls into view.
* The widget host sets `X-Frame-Options: ALLOWALL` and `frame-ancestors *`, so any origin can embed it.

## Theming

By default, every widget renders Cesto's canonical dark theme, so it looks consistent wherever it's embedded. If you want it to match your own site, you can override individual design tokens: colors, corner radius, fonts, and spacing.

### Theme fields

Every field is optional. Pass any subset; anything you don't set keeps the Cesto default.

| Field                           | Type             | What it controls                         |
| ------------------------------- | ---------------- | ---------------------------------------- |
| `accent` / `accentForeground`   | CSS color        | Primary action color, and the text on it |
| `background` / `foreground`     | CSS color        | Surface, and body text                   |
| `muted` / `mutedForeground`     | CSS color        | Secondary surfaces, and their text       |
| `border`                        | CSS color        | Borders and dividers                     |
| `positive` / `negative`         | CSS color        | Gains and losses                         |
| `radius`                        | px or length     | Corner rounding                          |
| `fontFamily` / `fontFamilyMono` | font stack       | Text and numeric fonts                   |
| `padding`                       | px or length     | Outer content padding                    |
| `maxWidth`                      | `none` or length | Cap on content width                     |

<Note>
  A bad value can't break a widget. Each field is validated on its own: an invalid value (say, `accent=notacolor`) is dropped and falls back to the Cesto default, and unknown params are ignored.
</Note>

### Setting a theme

The simplest way is to add the tokens as query params on the iframe URL, right alongside `basket`. Remember to URL-encode colors (`#` becomes `%23`):

```html theme={null}
<iframe
  src="https://widget.cesto.co/overview?basket=ai-leaders-portfolio&accent=%237c7cf0&radius=16&background=transparent"
  style="width: 100%; aspect-ratio: 2 / 1; border: 0;"
  loading="lazy"
></iframe>
```

<Tip>
  A widget's body is transparent by default, so it blends into your page background. Set `background` explicitly if you want it to fill with its own color.
</Tip>

### Live theming (optional)

To change the theme after load (for example, to follow a light/dark toggle on your page), the optional `@cesto/embed-sdk` host helper lets you push config in live and auto-resizes the iframe to fit its content:

```ts theme={null}
import { connectCestoFrame } from "@cesto/embed-sdk/host";

const iframe = document.querySelector("iframe")!;
const frame = connectCestoFrame(iframe);

// later, e.g. on a theme toggle:
frame.setConfig({ accent: "#7c7cf0", background: "#0b0d10" });
```

You can match your host's look by reading your own design tokens off the page and passing them straight in.

## What stays fixed

Theming covers look, not content. A widget's copy, its data, and the Invest destination (`app.cesto.co/product/<slug>`) are fixed and stay consistent with the rest of the Cesto product.

If you need anything beyond a themeable basket card on your page, that is a different surface and not a widget.

## Next

<CardGroup cols={1}>
  <Card title="Open the playground" icon="circle-play" href="/widgets/playground">
    Try every widget against any live basket, right inside the docs.
  </Card>
</CardGroup>