# Ignore known hydration mismatches

> Ignore known hydration mismatches without hiding new ones: skip elements and attributes, mask text, or accept one finding with a reason and an expiry date.

Source: https://hydration.jscrate.dev/docs/ignoring
Last updated: 2026-09-18

To ignore known hydration mismatches, add them to the `ignore` option: skip an
element's subtree, never compare an attribute, mask a text pattern, or accept
one finding with a reason and an expiry date. Ignored findings stay in the
report, marked as ignored with the reason, and do not fail the run.

## When to ignore known hydration mismatches

Ignoring is for markup that is meant to differ between the server and the
browser: an ad slot, analytics attributes, a third-party chat widget. A
difference in your own components is a bug, and the [causes](https://hydration.jscrate.dev/docs/causes)
pages show how to fix each one.

Prefer the narrowest tool, and write down why. For an app that already has many
findings, record a [baseline](https://hydration.jscrate.dev/docs/baselines) instead: it accepts today's
findings in one step and still fails on new ones.

| You want to                                               | Use                                                   |
| --------------------------------------------------------- | ----------------------------------------------------- |
| Skip an element in your own markup                        | The `data-hydration-proof-ignore` attribute           |
| Skip third-party markup you cannot edit                   | `ignore.selectors`                                    |
| Never compare an attribute, such as `data-gtm-*`          | `ignore.attributes`                                   |
| Ignore text that differs only in one part, such as a time | `ignore.textPatterns`                                 |
| Accept one known finding for a while                      | An `ignore.issues` rule with a `reason` and `expires` |
| Accept every current finding while you fix them           | A [baseline](https://hydration.jscrate.dev/docs/baselines)                         |
| Keep a value that differs on purpose, in the app itself   | `suppressHydrationWarning` (reported as info)         |

## Mark an element with data-hydration-proof-ignore

The subtree of any element with this attribute is not compared:

```tsx title="ad-slot.tsx"
export function AdSlot() {
  // The ad script fills this element before React hydrates.
  return <div id="ad-slot" data-hydration-proof-ignore />;
}
```

`[data-hydration-proof-ignore]` is always part of `ignore.selectors`, so
nothing else needs configuring.

## Ignore selectors, attributes and text patterns

For markup you cannot edit, list it in the config:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    // Third-party markup that is expected to differ.
    selectors: ["#ad-slot", "[data-chat-widget]"],
    // Attribute names, or patterns.
    attributes: [/^data-gtm-/],
    // "Updated 10:41" and "Updated 10:42" count as equal.
    textPatterns: [/\d{2}:\d{2}/],
  },
});
```

- `selectors`: elements whose subtree is not compared.
- `attributes`: attribute names (strings) or patterns (`RegExp`) that are
  never compared.
- `textPatterns`: a text difference is ignored when both values are equal after
  removing these patterns.

## Ignore one finding with a reason

An `ignore.issues` rule accepts specific findings. It matches on any
combination of `code`, `route` (a glob), `fingerprint` and `selector`, and every
field you give must match. `reason` is required and is shown in reports:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    issues: [
      {
        code: "HP4001",
        route: "/checkout",
        reason: "The payment iframe rewrites its container. Ticket ACME-431.",
        expires: "2026-12-31",
      },
    ],
  },
});
```

- `code`: an issue code, such as `HP1004`.
- `route`: a route glob, matched against the path and the route pattern.
- `fingerprint`: the exact fingerprint of one finding, from `report.json`.
- `selector`: a CSS selector prefix the finding must point at.
- `expires`: an ISO date after which the rule stops applying.

A fingerprint stays the same across runs as long as the problem does: the same
code, route pattern, element and attribute. It never depends on values that
change per request, so a rule written against it keeps matching.

> **An expired rule fails the run**
>
> After its `expires` date, a rule that still matches a finding fails the run
> with "Ignore rule "…" expired on 2026-12-31." That way a temporary exception
> cannot quietly become permanent: fix the finding, or extend the date on
> purpose.

## How suppressHydrationWarning differs from ignoring

`suppressHydrationWarning` changes your app: React keeps the server's text or
attribute on that element and does not report the difference. `ignore` changes
nothing in the app, only what hydration-proof reports.

hydration-proof still sees what `suppressHydrationWarning` hides, and audits it:

| Code                          | Severity | Finding                                                                                      |
| ----------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) | info     | A mismatch hidden by `suppressHydrationWarning`                                              |
| [HP6002](https://hydration.jscrate.dev/docs/issues/hp6002) | error    | A structural difference it cannot hide: it only covers the element's own text and attributes |
| [HP6003](https://hydration.jscrate.dev/docs/issues/hp6003) | info     | `suppressHydrationWarning` on an element with nothing to suppress                            |

`checks.suppressedWarnings` sets how much of this you see: `'info'` (the
default) lists the differences it hides, `'strict'` also flags unused
suppression, and `'off'` hides both. See
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning),
and the ESLint rule
[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
to catch misuse in your editor.

## Where ignored findings show up

Each report format handles ignored findings its own way:

- The terminal summary counts them as "Ignored issues".
- The HTML report hides them until you tick "Show ignored", then shows each
  one with the rule and the reason.
- SARIF includes them with an external suppression, so code scanning does not
  open alerts for them.
- JUnit lists them, but they never fail a test case. The GitLab Code Quality
  report leaves them out.

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `selectors` | `string[]` | — | Elements whose subtree is not compared. `[data-hydration-proof-ignore]` is always included. |
| `attributes` | `(string \| RegExp)[]` | — | Attribute names (or patterns) that are never compared. |
| `textPatterns` | `RegExp[]` | — | Text differences are ignored when both values are equal after removing these patterns. |
| `issues` | `IgnoreRule[]` | — | Ignore specific findings. |

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `code` | `string` | — | Issue code, e.g. `HP1004`. |
| `route` | `string` | — | Route glob. |
| `fingerprint` | `string` | — | Exact issue fingerprint from a report. |
| `selector` | `string` | — | CSS selector prefix the issue must point at. |
| `reason` (required) | `string` | — | Why this is ignored. Shown in reports. |
| `expires` | `string` | — | ISO date after which the rule stops applying (and CI fails). |

## Related

- [Baselines and budgets](https://hydration.jscrate.dev/docs/baselines) for existing findings
- [When suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [The `ignore` option](https://hydration.jscrate.dev/docs/configuration#ignore)
- [Reports](https://hydration.jscrate.dev/docs/reports): where fingerprints and ignored findings appear
- [Scripts that change the page before hydration](https://hydration.jscrate.dev/docs/causes/third-party-script)