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

# waitForDomSettled

Waits for DOM mutations to settle without executing any function first. This helper uses a MutationObserver to monitor DOM changes and waits until the DOM has been stable (no mutations) for the specified settle duration.

```typescript theme={null}
export declare function waitForDomSettled(options: {
  source: Page | Locator;
  settleDurationMs?: number;
  timeoutInMs?: number;
}): Promise<boolean>;
```

## `waitForDomSettled` vs `withNetworkSettledWait`

* Use `waitForDomSettled` when watching **DOM mutations** (elements added/removed/modified, loading spinners, dynamic content injection)
* Use [withNetworkSettledWait](../functions/withNetworkSettledWait) when watching **network requests** (API calls, form submissions, resource loading)

## Examples

<CodeGroup>
  ```typescript Wait After Navigation theme={null}
  import { waitForDomSettled } from "@intuned/browser";
  import { BrowserContext, Page } from "playwright";

  interface Params {}

  export default async function handler(
    params: Params,
    page: Page,
    context: BrowserContext
  ) {
    // Navigate to page with dynamic content
    await page.goto("https://sandbox.intuned.dev/lists/table");

    // Wait for all DOM mutations to complete
    const settled = await waitForDomSettled({
      source: page,
      settleDurationMs: 1000,
      timeoutInMs: 20000,
    });

    if (settled) {
      // DOM is stable, safe to extract data
      const rows = await page.locator("table tr").all();
      return rows.length;
    }
    return 0;
  }
  ```

  ```typescript Watch Specific Container theme={null}
  import { waitForDomSettled } from "@intuned/browser";
  import { BrowserContext, Page } from "playwright";

  interface Params {}

  export default async function handler(
    params: Params,
    page: Page,
    context: BrowserContext
  ) {
    await page.goto("https://sandbox.intuned.dev/lists/table");

    // Only watch table container (ignore header/footer changes)
    const table = page.locator("table");
    const settled = await waitForDomSettled({
      source: table,
      settleDurationMs: 800,
      timeoutInMs: 15000,
    });

    if (settled) {
      // Table has finished loading
      const rows = await table.locator("tr").count();
      return rows;
    }
    return 0;
  }
  ```
</CodeGroup>

## Arguments

<ResponseField name="options" type="Object" required>
  Configuration object for DOM settlement monitoring

  <Expandable title="properties" defaultOpen>
    <ResponseField name="options.source" type="Page | Locator" required>
      The Playwright Page or Locator to monitor for DOM changes. When a Page is provided, monitors the entire document. When a Locator is provided, monitors only that specific element.
    </ResponseField>

    <ResponseField name="options.settleDurationMs" type="number">
      Milliseconds the DOM must remain unchanged to be considered settled. Defaults to 500
    </ResponseField>

    <ResponseField name="options.timeoutInMs" type="number">
      Maximum milliseconds to wait before giving up. Defaults to 30000
    </ResponseField>
  </Expandable>
</ResponseField>

## Returns: `Promise<boolean>`

Promise that resolves to true if DOM settled within timeout, false if timeout or error occurred