> ## 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.

# Top List

> Ranked market lists for gainers, losers, active stocks, new highs, and other discovery workflows.

Top List helps users discover securities through ranked market presets. It can surface gainers, losers, active stocks, new highs, pre-market movement, or another supported screening result in a compact, scannable table.

<iframe data-widget-embed-slot="top-list" src="https://h5.ainvest.com/frontPage/regular/widgets-container/top-list-open-widget-preview.html" title="AInvest Top List 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                                          |
| ------------ | ------------------------------------------------------------------------------------------- | -------- | ------------- | ---------------------------------------------------- |
| `assetType`  | `"stock" or "etf" or "crypto"`                                                              | Yes      | `stock`       | Asset universe used by the ranking list.             |
| `listType`   | `"top_gainers" or "top_losers" or "most_active" or "best_performing" or "worst_performing"` | No       | `top_gainers` | Ranking preset shown in the list.                    |
| `defaultTab` | `"overview" or "valuation" or "performance" or "dividends" or "technical"`                  | No       | `overview`    | Initial metrics tab.                                 |
| `rowCount`   | `number`                                                                                    | No       | `50`          | Number of rows requested. Valid range: `1` to `200`. |

## Events

| Event      | Payload                                                | Description                          |
| ---------- | ------------------------------------------------------ | ------------------------------------ |
| `rowClick` | `{ symbol: string; exchange?: string; name?: string }` | Fired when a ranking row is clicked. |

## When to use Top List

* Market homepages that need a fast view of leading or unusual securities
* Pre-market and post-market discovery workflows
* Trading dashboards where selecting a row opens deeper symbol analysis
* Editorial pages that need a live ranking beside market commentary

Use [Heat Map](/widgets/api-reference/heat-map) when the goal is broad visual pattern recognition rather than an exact rank order.

## Core experience

Every list should identify its preset, market, session, ranking metric, and last-update time. Keep symbol, price, and the primary ranking value visible at all supported widths. Sorting and row selection must not obscure the meaning of the active preset.

When the selected session is closed, retain the latest valid ranking and label the session instead of presenting the list as live.

## Data and ranking states

Support loading, empty-result, market-closed, delayed-data, reconnecting, entitlement, and rate-limit states. If a preset returns no securities, explain whether the result is caused by filters, session timing, or data availability.

Rank changes should not cause disruptive row movement while the user is reading or interacting. Apply stable update behavior and preserve the selected row when possible.

## Responsive behavior

On small screens, keep symbol, price, and the ranking metric visible. Move secondary columns into an expandable row or detail view instead of forcing horizontal scrolling. Maintain comfortable tap targets for row selection and preset controls.

## Accessibility

* Use a semantic table or equivalent accessible grid structure.
* Announce the active preset and sort order.
* Provide row labels that include symbol, company name, rank, and primary metric.
* Do not rely on red and green alone to communicate gains or losses.
* Preserve visible keyboard focus during live ranking updates.

## Best practices

* Choose one primary ranking preset that matches the page's user intent.
* Show a clear session label for pre-market, regular, and post-market data.
* Limit visible rows to the space available and avoid nested scrolling where possible.
* Pair row selection with a chart or quote when deeper analysis is expected.
* Test empty filters, thinly traded sessions, and rapid ranking updates.

## Related widgets

* [Super Chart](/widgets/api-reference/super-chart) opens the selected security in a full analysis chart.
* [Heat Map](/widgets/api-reference/heat-map) adds a visual view of the same market universe.