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

# DOM Resources

> Read DOM elements as MCP resources for AI agent page inspection

`@frontmcp/react` provides two utility functions for reading DOM elements as MCP-compatible resources. These are useful when AI agents need to inspect page content.

## readDomById

Reads a DOM element by its `id` attribute and returns its HTML, text content, and tag name.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { readDomById } from '@frontmcp/react';

const result = readDomById('main-content');
// {
//   contents: [{
//     uri: 'dom://byId/main-content',
//     mimeType: 'application/json',
//     text: '{"outerHTML":"<div id=\"main-content\">...</div>","textContent":"...","tagName":"div"}'
//   }]
// }
```

### Return Values

| Scenario          | mimeType           | text                                                 |
| ----------------- | ------------------ | ---------------------------------------------------- |
| Element found     | `application/json` | JSON with `outerHTML`, `textContent`, `tagName`      |
| Element not found | `text/plain`       | `'Element with id "..." not found'`                  |
| No DOM (SSR)      | `text/plain`       | `'DOM not available (not in a browser environment)'` |

***

## readDomBySelector

Reads all elements matching a CSS selector.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { readDomBySelector } from '@frontmcp/react';

const result = readDomBySelector('.card');
// {
//   contents: [{
//     uri: 'dom://selector/.card',
//     mimeType: 'application/json',
//     text: '[{"outerHTML":"...","textContent":"...","tagName":"div"}, ...]'
//   }]
// }
```

### Return Values

| Scenario         | mimeType           | text                                                 |
| ---------------- | ------------------ | ---------------------------------------------------- |
| Elements found   | `application/json` | JSON array of `{ outerHTML, textContent, tagName }`  |
| No matches       | `text/plain`       | `'No elements found matching "..."'`                 |
| Invalid selector | `text/plain`       | `'Invalid selector: "..."'`                          |
| No DOM (SSR)     | `text/plain`       | `'DOM not available (not in a browser environment)'` |

***

## Use Case: AI Agent Page Inspection

Register DOM readers as MCP resource handlers so AI agents can inspect page content:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { create } from '@frontmcp/sdk';
import { readDomById, readDomBySelector } from '@frontmcp/react';

const server = await create({
  info: { name: 'browser-app', version: '1.0.0' },
  resources: [
    {
      uri: 'dom://byId/{id}',
      name: 'DOM Element by ID',
      read: ({ id }) => readDomById(id),
    },
    {
      uri: 'dom://selector/{selector}',
      name: 'DOM Elements by Selector',
      read: ({ selector }) => readDomBySelector(decodeURIComponent(selector)),
    },
  ],
});
```

An AI agent can then call `readResource('dom://byId/login-form')` to inspect a form, or `readResource('dom://selector/.error-message')` to check for error states on the page.

<Note>
  When using `readDomBySelector` with complex selectors (e.g., `div > .my-class`), the selector is embedded in the URI path. Use `encodeURIComponent` when constructing the URI to avoid parsing issues: `dom://selector/${encodeURIComponent('div > .my-class')}`.
</Note>