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

# Watchlist

> Personalized security list for tracking symbols, prices, movement, and market context.

Watchlist helps users monitor selected securities in one place. It is designed for portfolio-adjacent workflows, market tracking, and symbol lists that need quick price context before opening deeper analysis.

<iframe data-widget-embed-slot="watchlist" src="https://h5.ainvest.com/frontPage/regular/widgets-container/watchlist-open-widget-preview.html" title="AInvest Watchlist widget preview" style={{ display: "block", width: "100%", height: "min(80vh, 900px)", minHeight: "720px", maxHeight: "900px", border: 0, borderRadius: "12px", overflow: "hidden" }} loading="lazy" allow="clipboard-write; fullscreen" allowFullScreen referrerPolicy="strict-origin-when-cross-origin" />

## Properties

### Common properties

| Name              | Type                         | Required | Default      | Description                                                                |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme`           | `"light" or "dark"`          | No       | `light`      | Visual theme applied inside the widget iframe.                             |
| `locale`          | `string`                     | No       | `en`         | Locale used by labels, formatting, and component copy when supported.      |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No       | `GreenForUp` | Controls whether green or red represents positive price movement.          |
| `autoHeight`      | `boolean`                    | No       | `true`       | Enables ResizeObserver-driven iframe height updates through `postMessage`. |

### Widget properties

| Name            | Type                | Required | Default | Description                                                               |
| --------------- | ------------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `styleVariant`  | `"tiny" or "loose"` | No       | `tiny`  | Watchlist density and row spacing.                                        |
| `activeGroupId` | `string`            | No       | \`\`    | Watchlist group to open by default. Leave empty to use the default group. |
| `hideTabs`      | `boolean`           | No       | `false` | Hides the watchlist group tabs.                                           |

## Events

| Event      | Payload                              | Description                            |
| ---------- | ------------------------------------ | -------------------------------------- |
| `rowClick` | `{ symbol: string; market: string }` | Fired when a watchlist row is clicked. |

## When to use Watchlist

* Portfolio, account, or research dashboards that need a saved symbol list
* Market workspaces where users repeatedly return to the same securities
* Sidebars that coordinate a selected symbol with charts, quotes, or news
* Pages that need compact price movement across multiple user-selected names

Use [Top List](/widgets/api-reference/top-list) when the list should be generated from a ranking preset rather than a saved or curated symbol set.

## Core experience

Each row should identify the symbol, company or asset name, latest price, price change, market session, and timestamp. Keep the selected symbol clear when Watchlist drives a surrounding chart, quote, or news component.

## Data and market states

Support loading, empty-list, invalid-symbol, delayed-data, market-closed, entitlement, reconnecting, and error states. If a list is empty, provide a direct recovery path instead of showing inactive rows.

## Responsive behavior

On narrow screens, prioritize symbol, price, change, and session. Secondary columns can collapse into a detail row or compact metadata area. Avoid horizontal page scrolling.

## Accessibility

* Use row labels that include symbol, company name, price, and movement.
* Do not rely on color alone for positive and negative changes.
* Preserve visible focus for row actions and selected symbols.
* Keep price updates readable without excessive live announcements.
* Give the iframe a descriptive title that includes “AInvest Watchlist.”

## Best practices

* Keep the default symbol list short enough to scan.
* Preserve row order while users are reading live updates.
* Synchronize row selection with related widgets when used in a dashboard.
* Test empty lists, invalid symbols, delayed data, and reconnecting states.

## Related widgets

* [Super Chart](/widgets/api-reference/super-chart) opens the selected security in a full analysis chart.
* [Quick Quote](/widgets/api-reference/quick-quote) shows compact quote details for the selected symbol.