# Loading and empty results

Loading and empty-data messages explain why the table has no visible content. Pending requests, no results, and failures are distinct states and should not share one empty screen.

Canonical: https://grid.syidax.com/docs/features/overlays/

<a id="understand"></a>

## How it works and when to use it

Enable loading while the app fetches data and clear it when the request ends, whether it succeeds or fails. Configure empty results with showEmptyState and emptyMessage, and provide error retries in the app.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. Initial query

Assume readOrders is a data-fetching function implemented by your app.

```javascript
grid.loading = true;
grid.loadingMessage = 'Loading orders.';
try {
  grid.rowData = await readOrders();
} finally {
  grid.loading = false;
}
```

Verify the result: The table appears on success, and loading clears even on failure. The calling app must explain errors.

<a id="example-2"></a>

## Example 2. When a query returns no results

An empty array can be a valid query result.

```javascript
grid.showEmptyState = true;
grid.emptyMessage = 'No matching orders. Check your search criteria.';
grid.rowData = [];
```

Verify the result: Users can understand whether to change their search criteria. While a request is pending, show loading instead of an empty state.

<a id="example-3"></a>

## Example 3. Fast refreshes and flicker

For repeated short requests, adjust display duration with minLoadingDuration. Decide whether to retain existing data based on the app workflow.

Verify the result: When filters change rapidly, implement cancellation or request ordering so an older response cannot overwrite the latest result.

<a id="pitfalls"></a>

## Combining features and troubleshooting

Use distinct messages for empty data and server errors. Explain failure causes and whether retry is possible.

For long tasks, provide necessary actions such as progress, cancellation, and retry instead of relying only on a loading screen.

<a id="related-api"></a>

## APIs used by this feature

- [showEmptyState](https://grid.syidax.com/docs/options/showEmptyState.md) — Shows an empty-state message when no data exists. Distinguish request failures from valid empty results in your app.
- [emptyMessage](https://grid.syidax.com/docs/options/emptyMessage.md) — Message displayed when source data is empty.
- [noMatchesMessage](https://grid.syidax.com/docs/options/noMatchesMessage.md) — Message displayed when data exists but no rows match current search or filters.
- [clearFiltersLabel](https://grid.syidax.com/docs/options/clearFiltersLabel.md) — Label for the clear-filters action in an empty-results view.
- [loading](https://grid.syidax.com/docs/options/loading.md) — Displays app data-request progress. Clear it after both success and failure.
- [loadingMessage](https://grid.syidax.com/docs/options/loadingMessage.md) — Description shown while loading.
- [loadingMode](https://grid.syidax.com/docs/options/loadingMode.md) — Selects the Grid loading indicator. See LoadingMode for supported values.
- [minLoadingDuration](https://grid.syidax.com/docs/options/minLoadingDuration.md) — Minimum loading-indicator duration to avoid brief flashes.
- [emptyStateActionClicked](https://grid.syidax.com/docs/events/emptyStateActionClicked.md) — Emitted when an empty-state action button is clicked. Connect the app flow appropriate to the action type.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/overlays) — The guide describes which interactions are available to try.