renderlintv0.2.0

All 52 renderlint rules

Each rule checks the rendered page, not the source. 29 rules are errors by default and fail the run (exit code 1); the rest are warnings. Every rule can be set to "error", "warn" or "off" in renderlint.config.json, and npx renderlint explain <rule> prints the same text in the terminal.

Layout

text-overflow error

Text spills outside the box (card, button, badge, input) that is supposed to contain it.

How to fix: Let the text wrap: remove fixed widths/heights or white-space: nowrap, add overflow-wrap: anywhere (Tailwind break-words) for long words/URLs, and use min-width: 0 on flex/grid children so they can shrink.

Read more: How to find text overflow and clipped text in responsive layouts · Visual regression testing vs rendered-UI linting

text-crowding error

Text still fits inside its card, button or badge, but has run through the side padding and nearly touches the edge (a KPI number, a long label).

How to fix: Give the text room to shrink or wrap: min-width: 0 and overflow-wrap: anywhere on flex/grid children, a fluid font size for big numbers (font-size: clamp(1.5rem, 4cqi, 2.5rem) with container-type: inline-size on the card), fewer columns at that width, or a shorter format (4.9K).

Read more: How to find text overflow and clipped text in responsive layouts

text-clipped error

Text is partially cut off by an overflow: hidden container or the edge of an &lt;svg> (e.g. chart axis labels).

How to fix: Give the container room (remove fixed height, add padding), allow wrapping, or truncate intentionally with text-overflow: ellipsis / line-clamp. For SVG charts increase the chart margin/padding or rotate/shorten labels.

Read more: How to find text overflow and clipped text in responsive layouts · How to catch UI bugs written by AI coding agents

unreachable-content error

Content lies below the bottom of a box that clips (overflow: hidden or clip), or below the screen on a page that doesn't scroll, and nothing around it scrolls: users can never see it. Typical causes: a fixed-height app shell (height: 100vh; overflow: hidden) whose page or tab area isn't a scroller, or a scroll lock (body { overflow: hidden }) left on. Before reporting, renderlint turns the mouse wheel over the box: content that a script scrolls is not reported. Not reported: content moved away on purpose (transformed, absolute or fixed), small boxes (teasers, collapsed panels), boxes with a "Show more" control, faded or line-clamped text, and the page while a dialog is open.

How to fix: Make the area that grows scroll: overflow-y: auto on it, and in a flex or grid layout let it shrink to the space it has (flex: 1 1 0%; min-height: 0, or min-height: 0 on the grid row) so it doesn't just grow past its parent. Or remove the fixed height so the page scrolls. Remove a scroll lock when what set it closes.

Read more: Content you can't scroll to: 100vh app shells, scroll locks and tall modals · Visual regression testing vs rendered-UI linting

content-overflow error

A child element (image, button, inner card) sticks out of its visible container.

How to fix: Constrain the child (max-width: 100%, min-width: 0 on flex children, flex-wrap: wrap) or let the container grow instead of using a fixed size.

accidental-scrollbar error

A scroll container overflows by only a few pixels, showing a pointless scrollbar.

How to fix: Fix the few pixels of overflow (often padding + fixed height, or 100vh/100vw plus margins) or use overflow: hidden/visible if scrolling is not intended.

Responsive

viewport-overflow error

Content is wider than the viewport: the page scrolls sideways on phones, or content is cut off at the screen edge.

How to fix: Replace fixed pixel widths with fluid ones (max-width: 100%, w-full), make rows wrap (flex-wrap), collapse grids to fewer columns at small breakpoints (grid-cols-1 md:grid-cols-3), and break long words.

Read more: How to find text overflow and clipped text in responsive layouts

missing-viewport-meta error

No &lt;meta name="viewport"> tag, so mobile browsers render the page zoomed out at desktop width.

How to fix: Add &lt;meta name="viewport" content="width=device-width, initial-scale=1"> to <head>.

fragile-layout warning

Stress test: the layout breaks with content the sample data doesn't have yet: ~50% longer text, long unbreakable emails/URLs/IDs, numbers with three more digits, longer API data, or the worst case declared with data-renderlint-maxlength / data-renderlint-sample (that last one is an error).

How to fix: Design for longer content: allow wrapping, avoid fixed heights/widths on text containers, add min-width: 0 to flex children and overflow-wrap: anywhere for long words.

Read more: How to find text overflow and clipped text in responsive layouts · How to catch UI bugs written by AI coding agents · Visual regression testing vs rendered-UI linting

Overlap

text-overlap error

Two pieces of text are drawn on top of each other — overlapping labels in charts, diagrams, absolutely positioned captions, or collapsed layouts.

How to fix: Give elements space (no fixed heights, avoid absolute positioning for flowing content). For charts: reduce tick count, rotate or truncate labels, increase chart margins, or use a legend instead of inline labels.

element-overlap error

Boxes that are laid out side by side (cards, buttons, images) overlap each other, typically after the viewport shrinks.

How to fix: Use flex-wrap/grid with responsive columns instead of fixed widths; remove fixed heights that force content into the next element.

obscured-content error

Text or a control is hidden underneath another opaque element (fixed header covering the hero, absolutely positioned image over a button).

How to fix: Offset content below fixed/sticky headers (padding-top / scroll-margin), fix z-index stacking, or reposition the covering element.

Color

contrast error

Text does not have enough contrast with what is actually behind it (WCAG AA: 4.5:1, or 3:1 for large text). Measured from real rendered pixels, so it works over gradients and images.

How to fix: Use the suggested color (or darker/lighter), change the background, or add an overlay/scrim behind text on images. Check dark mode separately.

Read more: How to measure color contrast on gradients and background images · How to catch UI bugs written by AI coding agents · Visual regression testing vs rendered-UI linting

Polish

emoji error

Emoji used as icons or decoration in the interface.

How to fix: Replace emoji with icons from a real icon set rendered as SVG (lucide, heroicons, phosphor, tabler, material symbols…). If emoji are genuinely content (chat messages, user input), mark the element with data-renderlint-ignore="emoji".

Read more: How to catch UI bugs written by AI coding agents

oversized-icon error

An icon-sized SVG (viewBox ≤ 48) renders huge because it has no width/height, so it stretches to fill its container.

How to fix: Give icons an explicit size: width/height attributes or CSS (e.g. width: 1.25rem; height: 1.25rem, Tailwind size-5), and flex-shrink: 0 in flex rows.

button-text-wrap warning

A short button label breaks onto multiple lines.

How to fix: Shorten the label, allow the button to grow (remove fixed width), or use white-space: nowrap with enough room.

icon-misaligned warning

An icon next to a single line of text sits visibly above or below the text's center (an inline SVG on the baseline, or a larger icon next to small text).

How to fix: Lay the icon and text out with display: inline-flex; align-items: center; gap: 6px, and give the icon flex-shrink: 0.

native-dialog error

The app uses the browser's own alert(), confirm() or prompt() box: a grey system dialog that blocks the page, ignores the app's design and can't be styled or translated. Found when one opens while a page is checked, and in source code (window.confirm(…), alert(…)), which also catches the ones behind a click. The browser's "Leave site?" prompt from beforeunload is not flagged.

How to fix: Use the app's own UI: a toast or snackbar for notices ("Saved"), an inline message next to the field for validation errors, and a modal dialog component for confirmations ("Delete this project?") and for asking for a value (the &lt;dialog> element, Radix / shadcn AlertDialog, Headless UI Dialog, Angular Material MatDialog, Vuetify v-dialog…). If one is really intended, add // renderlint-ignore native-dialog on the line above.

Read more: How to replace alert(), confirm() and prompt() in a web app

Content

placeholder-text error

Leaked placeholders or broken data: [object Object], undefined, NaN, Invalid Date, {{template}}, lorem ipsum, TODO. On WordPress sites also the sample content ("Hello world!", "Just another WordPress site") and Elementor's default widget texts ("Add Your Heading Text Here").

How to fix: Render real content: fix the data binding / formatting, provide fallbacks for missing values, and replace lorem ipsum with real copy. WordPress: delete the sample post, page and comment, and set a tagline (Settings > General) or remove it from the theme.

broken-image error

An image failed to load or has no src.

How to fix: Fix the path/URL (check the public/static folder and base path) or remove the image.

image-distortion error

An image is rendered at a different aspect ratio than its natural one (stretched or squashed).

How to fix: Set only one dimension (height: auto) or use object-fit: cover / contain with a fixed box.

invisible-content error

In-flow content (text) that is still transparent or visibility: hidden after scrolling through the page, leaving a blank gap: usually a scroll-reveal animation that never fires (IntersectionObserver threshold too high for tall sections on phones, a missing "visible" class, or an Elementor/WOW.js entrance animation whose script was delayed by an optimisation plugin or broken by a JavaScript error).

How to fix: Use a low IntersectionObserver threshold (0–0.15) or rootMargin, reveal elements already in view on load, and make content visible by default when JS or animations are unavailable (prefers-reduced-motion). WordPress: exclude Elementor's frontend scripts (and jQuery) from "delay JavaScript" in WP Rocket/Perfmatters/LiteSpeed, check the console for errors, or remove the entrance animation.

Accessibility

missing-alt warning

An &lt;img> has no alt attribute.

How to fix: Add a short description (alt=&quot;Team photo&quot;) or alt=&quot;&quot; if the image is decorative.

nested-interactive error

A link or button nested inside another link or button (invalid HTML; causes hydration errors and unpredictable clicks).

How to fix: Restructure so interactive elements are siblings (e.g. stretched-link pattern with a positioned ::after).

tap-target warning

A button/link is smaller than 24×24px (WCAG 2.2 AA), hard to hit on touch screens.

How to fix: Increase padding or min-width/min-height (44×44px recommended for primary touch targets).

unlabeled-control warning

An icon-only button/link or a form field without an accessible name.

How to fix: Add aria-label to icon buttons, and a <label> (or aria-label) to form fields.

focus-indicator warning

A focusable element shows no visible change when focused (outline removed without replacement).

How to fix: Keep the outline or add a :focus-visible style (e.g. Tailwind focus-visible:ring-2).

Readability

font-size-min warning

Text smaller than 12px.

How to fix: Use at least 12px (14–16px for body text).

line-length warning

Paragraph lines are very long (>120 characters), which is tiring to read.

How to fix: Constrain text width, e.g. max-width: 65ch (Tailwind max-w-prose).

Forms

checkbox-layout error

A checkbox or radio button is stretched to the full width (drawn in the middle, away from its label), or sits on its own row above its label.

How to fix: Scope full-width input styles to text fields (input:not([type=checkbox]):not([type=radio])), give checkboxes width: auto (Tailwind w-4 h-4 shrink-0), and put the box and label in a row: display: flex; align-items: center; gap: 8px (or items-start for multi-line labels).

Read more: Form controls that render wrong: dropdown arrows, checkboxes and input icons

input-icon-overlap error

An icon (search, mail, calendar) is drawn over the part of an input where its text and placeholder appear, so typed text runs underneath it.

How to fix: Add padding on the icon's side so the text starts after it: e.g. padding-left: 40px (Tailwind pl-10) for a 16px icon at left: 12px, or pr-10 for a trailing icon.

Read more: Form controls that render wrong: dropdown arrows, checkboxes and input icons

squashed-control error

An input or select is too short for its text: height minus vertical padding leaves less room than the font needs, so the text is cut off at the top and bottom.

How to fix: Remove the fixed height or reduce vertical padding: use either height with padding-block: 0, or padding with height: auto. A 16px font needs about 20px of content height.

Read more: Form controls that render wrong: dropdown arrows, checkboxes and input icons

control-height-mismatch warning

Controls placed side by side (an input and its button, a select next to a text field) have different heights, so their edges don't line up.

How to fix: Give controls in a row the same height (e.g. h-10 on both), or let the row stretch them: display: flex; align-items: stretch.

Read more: Form controls that render wrong: dropdown arrows, checkboxes and input icons

UX

loading-state warning

An area of the page stays blank while its data loads: no spinner, skeleton, progress bar or "Loading…" text, so on a slow connection the page looks empty, broken or frozen. renderlint reloads each page with its fetch/XHR requests held for a second (as on a slow network), looks at what is shown, releases them and finds the areas the data filled. Any loading sign on the page counts: aria-busy, role=progressbar/status, a running animation, motion on screen, "Loading…"/"Saving…" text, skeleton or spinner class names, placeholder blocks where the content appears. With --ux, also checked after each click.

How to fix: Render a loading state where the data will appear until it arrives: a skeleton shaped like the content (best: no layout jump), or a spinner. With TanStack Query / SWR use isPending / isLoading; with React Suspense a fallback; with React Router loaders useNavigation(); in Next.js a loading.tsx. Show an error message if the request fails.

Read more: Loading states and layout shift: testing what users see on a slow network

action-feedback warning

After a click (a button, tab, link or form submit), the request it starts takes a while and nothing on screen changes meanwhile: the page looks frozen, and users click again or leave. Checked by --ux, which holds the request for a second (Nielsen: past 1s users lose the feeling of direct control). Covers in-app page changes too (React Router loaders, Next.js navigation without loading.tsx).

How to fix: Respond to the click at once: a pending state on the control (spinner, "Saving…", disabled) or where the result will appear (skeleton, dimmed old content with aria-busy, a top progress bar for page changes: useNavigation(), Next.js loading.tsx, NProgress), then the result.

Read more: Loading states and layout shift: testing what users see on a slow network

ui-freeze warning

The page could not respond or repaint for 500ms or more: a long task blocked the main thread while loading, or after a click (Interaction to Next Paint over 500ms is rated poor). Checked by --ux.

How to fix: Find the long task in the Performance panel. Move heavy computation to a Web Worker, split work into chunks that yield (await scheduler.yield() / setTimeout), virtualize long lists, and in React wrap slow updates in startTransition so feedback paints first.

error-feedback warning

When a request fails, nothing tells the user: the page shows less (or keeps its spinner forever) on load, or an action seems to succeed. --ux answers the page's data requests, and each action's, with HTTP 500 and looks for an error message, an alert or a changed control.

How to fix: Handle the failed request in the UI: an error message where the content would be, or a toast / inline error for an action, saying what went wrong and offering a retry; stop the loading state and re-enable the control. (TanStack Query isError, SWR error, a catch that sets error state, an error boundary.)

Read more: Loading states and layout shift: testing what users see on a slow network

double-submit warning

Clicking a submit or save button twice while its request is pending sends it twice: duplicate orders, payments or messages. Checked by --ux on actions that change data (POST, PUT, PATCH, DELETE; renderlint answers them itself, nothing reaches the server).

How to fix: Disable the button (or ignore clicks) while the request is in flight, and show that it is working ("Saving…"). For payments and orders, also send an idempotency key.

dead-control warning

A button that does nothing a user can see when clicked: no request, no change on screen, no navigation, dialog or download. Checked by --ux.

How to fix: Fix the handler (missing, failing, or attached to another element). If the result is invisible (copied to the clipboard, saved in the background), confirm it with a "Copied" label or a toast. A placeholder button should be disabled or removed.

slow-render warning

The page's main content appears more than 4s after navigation (Largest Contentful Paint, measured by --ux on a reload from the local server with a warm cache; Core Web Vitals rates over 4s as poor).

How to fix: Find what delays the content: request waterfalls (requests that wait for each other: start them together, or fetch on the server), a large bundle before the first render (code-split routes, lazy-load heavy components), or render-blocking resources.

layout-shift warning

Content jumps around while the page loads (Cumulative Layout Shift over 0.1, the Core Web Vitals limit for "good"): text and buttons move as data and images arrive, so users lose their place or click the wrong thing. Measured while the loading-state check holds the page's data for a second and releases it.

How to fix: Reserve the space before the content arrives: a skeleton the size of the content, width and height (or aspect-ratio) on images, video and embeds, min-height on areas filled by data, and no banners inserted above existing content.

Read more: Loading states and layout shift: testing what users see on a slow network

empty-state warning

With no data yet (a new account, a filter that matches nothing), a list, table or chart is just empty, keeps loading, or the page breaks: nothing says there is nothing yet. --ux reloads the page with every list of records in its JSON responses emptied ({ &quot;items&quot;: [], &quot;total&quot;: 0 }: arrays of objects with an id, but not the user’s roles, flags, settings, menus or lookup lists; renderlint answers, nothing changes on the server) and looks for a message where the content was. A section hidden entirely, title and all, is left alone.

How to fix: Render an empty state where the content would be: a short message ("No orders yet") and, when the user can add one, the action that does it ("Create order"). Guard code that assumes at least one record (items[0].name, reduce() with no initial value, a chart with no points).

dialog-focus warning

A dialog opened by a click doesn't handle focus as users expect (WAI-ARIA dialog pattern, WCAG 2.4.3): focus stays on the page behind it, Escape doesn't close it, or when it closes focus drops to the top of the page instead of returning to the control that opened it. Checked by --ux on the modal dialogs its clicks open (&amp;lt;dialog&gt; with showModal(), aria-modal, alertdialog, or a dialog over a full-screen overlay).

How to fix: Use a dialog that manages focus: the &amp;lt;dialog&gt; element opened with showModal(), or Radix / Headless UI / MUI / Angular CDK dialogs. By hand: focus the first field (or the close button) on open, close on Escape, and on close call .focus() on the element that opened it.

Read more: How to replace alert(), confirm() and prompt() in a web app

back-navigation warning

After an in-app link (a client-side route change), the browser's Back button doesn't bring the previous page back: the route change replaced the history entry, so Back skips the page, or the address changes back while the page keeps showing the new one (the app ignores popstate). Checked by --ux on in-app links that change the route.

How to fix: Navigate with the router's own links and push navigation (&lt;Link&gt;, router.push, navigate(path)); keep replace for redirects. If you change the URL with history.pushState yourself, render the matching view on popstate.

Runtime

page-error error

The page could not be loaded or analyzed: navigation failed, timed out, or returned an HTTP error (4xx/5xx).

How to fix: Make sure the page exists and the server is running (check the URL, routes and serve command), then fix any server error.

auth-required error

A page renderlint was asked to check sent it to a login page or identity provider instead, so the page itself was never checked. A warning for pages found by crawling, and for a home page that is the sign-in page (which is then checked itself). Any other page the app didn't show is page-not-shown.

How to fix: Add "auth" to renderlint.config: log in once with auth: { login: &quot;/login&quot;, user: &quot;${RENDERLINT_USER}&quot;, password: &quot;${RENDERLINT_PASSWORD}&quot; }, or, frontend only with no backend, set what the route guard reads (auth: { storage: { sessionStorage: { &quot;token&quot;: &quot;test&quot; } } }) and serve the API with mock. For a role: give it a session the app accepts (its storage or login under roles.&lt;name&gt;). See docs/authentication.md.

Read more: How to test every route and role behind a login

page-not-shown warning

Signed in, the app did not show a page renderlint was asked to check or found (in a link or the app's routes), so it was not checked: a guard redirected elsewhere, the server answered HTTP 401/403, or "Access denied" / "Page not found" was rendered in its place. With several roles, a page one role sees and another does not. An error for a page you listed that no role could see, and for a page in a role's own pages. Not flagged: the home page forwarding, a section's default child, trailing slashes, locale prefixes, and a redirect every role takes the same way.

How to fix: If the role is not meant to see the page, list it in roles.&lt;role&gt;.deny (e.g. ["/admin/**"]) and it is recorded as denied as expected. Otherwise give that role what the guard checks (its storage, a forged token { &quot;$jwt&quot;: { &quot;role&quot;: &quot;admin&quot; } }, or roles.&lt;role&gt;.mock, e.g. /api/me answering with that role), or for a dynamic route set params to a value that exists. See docs/roles-and-coverage.md.

Read more: How to test every route and role behind a login

console-error error

Uncaught JavaScript error or console.error while rendering (hydration mismatches, crashed components).

How to fix: Open the page, read the error, and fix the underlying bug.

broken-resource error

A same-origin stylesheet, script, font or image request failed (404/500), or a web font failed to load.

How to fix: Fix the asset path or remove the reference.

Intentional exceptions

When a finding is intentional (a watermark, a teaser, a chat message that contains emoji), mark the element. The mark applies to the element and its descendants, and is reviewed like an eslint-disable.

<div data-renderlint-ignore="emoji" data-renderlint-reason="user-generated chat">…</div>
<p data-renderlint-ignore>…</p>   <!-- all rules, this subtree -->
.watermark { --renderlint-ignore: contrast; }   /* from CSS, inherited */

In source files (static scan), write // renderlint-ignore emoji on the line or the line above, or renderlint-ignore-file anywhere in the file. Config can also ignore by selector or page: "ignore": [{ "rule": "contrast", "selector": ".legal" }].