Ignore known hydration mismatches

To ignore known hydration mismatches, use the ignore option. You can exclude a subtree, attribute, text pattern, or specific finding. Ignored findings stay in the report with a reason, but do not fail the run.

When to ignore known hydration mismatches

Use ignore rules for markup you expect a third party to change, such as an ad slot or analytics attribute. Fix differences in your own components; the cause guides can help.

Keep each rule as narrow as you can, and record why it exists. If you need to accept many existing findings while fixing them, use a baseline. New findings will still fail the check.

Mark an element with data-hydration-proof-ignore

Add this attribute to markup you own when its contents should not be compared:

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

No config is needed for data-hydration-proof-ignore.

Ignore selectors, attributes and text patterns

For third-party markup you cannot edit, configure what to skip:

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

Use ignore.issues to accept a particular finding. Match it by code, route, fingerprint, or selector. Every field you provide must match, and reason is required:

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 identifies the same issue code, route, element, and attribute across runs. It does not include a value that changes on each request.

How suppressHydrationWarning differs from ignoring

suppressHydrationWarning changes React's behavior in your app. An ignore rule changes only the hydration-proof result; it does not change the page.

hydration-proof also reports differences hidden by suppressHydrationWarning:

checks.suppressedWarnings controls these findings. The default, 'info', lists hidden differences. 'strict' also flags unused props; 'off' hides both. See when suppression is safe and the audit-suppress-hydration-warning ESLint rule.

Where ignored findings show up

Ignored findings appear differently in each report:

• 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

Related

• Baselines and budgets for existing findings
• When suppressHydrationWarning is safe
• The ignore option
• Reports: where fingerprints and ignored findings appear
• Scripts that change the page before hydration