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

# Market Calendar

> Scheduled earnings and market events with timing, estimates, actuals, and surprise context.

Market Calendar organizes scheduled events into a daily or weekly view. It is designed to help users understand when earnings, economic releases, dividends, splits, or other supported market catalysts are expected.

<iframe data-widget-embed-slot="market-calendar" src="https://h5.ainvest.com/frontPage/regular/widgets-container/market-calendar-open-widget-preview.html" title="AInvest Market Calendar 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                         |
| ------------------ | ---------------------------- | -------- | ---------- | ----------------------------------- |
| `initialDataType`  | `"earnings" or "economic"`   | No       | `earnings` | Event category shown on first load. |
| `initialViewMode`  | `"day" or "week" or "month"` | No       | `week`     | Calendar view shown on first load.  |
| `variant`          | `"tiny" or "loose"`          | No       | `tiny`     | Calendar density and spacing.       |
| `hideDateSelector` | `boolean`                    | No       | `false`    | Hides the date selector controls.   |

## Events

| Event         | Payload                                 | Description                                                  |
| ------------- | --------------------------------------- | ------------------------------------------------------------ |
| `symbolClick` | `{ symbol: string; exchange?: string }` | Fired when a security symbol inside an event row is clicked. |

## When to use Market Calendar

* Earnings hubs and scheduled-event pages
* Portfolio or watchlist tools that need upcoming catalysts
* Trading dashboards that separate pre-market and post-market events
* Editorial workflows that contextualize market-moving dates

## Core experience

Every event should communicate its date, event type, entity or symbol, applicable reporting period, session timing, and current status. Earnings events may include EPS and revenue estimates, actual values, and surprise calculations when available.

Use a clearly stated timezone for all dates and session labels. Distinguish confirmed values from estimates and pending reports.

## Data and event states

Support loading, empty-date, no-filter-results, upcoming, reported, postponed, cancelled, delayed-data, entitlement, and error states. When an actual value has not been reported, keep the field explicitly pending rather than substituting zero.

If event timing changes, show the latest status and avoid silently moving an event without updating its label.

## Responsive behavior

On smaller screens, group events by day and prioritize event name, symbol, timing, and status. Move secondary estimates or surprise metrics into an expandable detail view. Preserve date navigation without requiring horizontal page scrolling.

## Accessibility

* Do not rely on calendar position alone to communicate an event date.
* Provide accessible labels for date navigation and filter controls.
* Identify estimate, actual, surprise, and pending values in text.
* Make event rows reachable and actionable by keyboard.
* Use a descriptive iframe title and a visible timezone label.

## Best practices

* Default to the event type that matches the page's primary intent.
* State the timezone and visible date range near the top of the widget.
* Avoid combining unrelated event types when it reduces scannability.
* Preserve the user's date and filter state during data refreshes.
* Test weeks with no events, postponed reports, and missing estimates.

## Related widgets

* [News Wire](/widgets/api-reference/news-wire) pairs scheduled events with timely market coverage.
* [Top List](/widgets/api-reference/top-list) shows securities moving around major catalysts.