Embed

One script tag on your 404 page.

The snippet detects a 404, reports the hit to your 404less instance, and shows the visitor a “Looking for something?” card with the closest known pages. Nothing happens on any other page.

Install How it detects a 404 Options Styling JavaScript API Privacy

acme.dev /docs/getting-startd

404
Detected
```
<script src="…/embed.js" data-site="…" defer>
```
From the title, a meta tag or data-404. Nothing runs on other pages
Reported

URL, referrer and title to /api/track. No cookies
Suggested

“Looking for something?” with the closest known pages, in a shadow root

Install

Paste this into your 404 template, replacing the key with the one from Site settings → Install:

<script src="https://your-404less.example/embed.js" data-site="SITE_KEY" defer></script>

Site settings has per-platform tabs (HTML, Next.js, WordPress, Astro) and an Ask your agent prompt that carries the snippet, the key and a verification step. Preview the widget opens a stand-in 404 page against your key, so you can see the result before touching your site.

How it detects a 404

Browsers don’t expose the HTTP status to scripts, so the snippet checks, in order:

data-404="true" on the script tag itself (the explicit option, recommended when you control the template).
window.__404less.is404 === true, for single-page apps.
data-404 on <html> or <body>.
A <meta name="prerender-status-code" content="404"> or <meta name="404less" content="404"> tag.
The document title: “404”, “not found”, or “page doesn’t exist”.

If your 404 template is shared with other error pages, set data-404="false" on those to opt out explicitly.

Options

All options are data- attributes on the script tag.

Attribute	Values	Default
`data-mode`	`toast` floating card · `inline` renders into `data-target`	`toast`
`data-target`	CSS selector of the container for inline mode	the script’s parent
`data-theme`	`auto` · `light` · `dark`	`auto`
`data-accent`	Any CSS color, for the icon and the best match	graphite
`data-title`, `data-text`	Heading and intro copy	“Looking for something?”
`data-position`	`right` · `left` · `center` (desktop toast)	`right`
`data-max`	1–5 suggestions	`3`
`data-track`	`false` to only show suggestions	`true`
`data-branding`	`false` to hide “Powered by 404less”	`true`
`data-url`	Absolute URL to report instead of `location.href`	-

Inline example

<div id="suggestions"></div>
<script src="https://your-404less.example/embed.js" data-site="SITE_KEY"
        data-mode="inline" data-target="#suggestions" data-404="true" defer></script>

Inline mode also shows a “Go to the homepage” fallback when there is no close match. The toast shows nothing in that case.

Styling

The card lives in a shadow root, so your stylesheet can’t accidentally restyle it and it can’t restyle your page. Colors are custom properties you can set on the host element:

.f404less {
  --f404-accent: #e11d48;
  --f404-bg: #fff;      --f404-fg: #111;
  --f404-muted: #666;   --f404-border: #ddd;
  --f404-radius: 12px;
}

Motion follows prefers-reduced-motion; dark mode follows prefers-color-scheme unless you set data-theme. A dismissed toast stays dismissed for the session.

JavaScript API

For client-side routers that render a 404 state without a page load, the snippet exposes a small API on window.__404less:

// after your router decides the route doesn't exist
window.__404less.track();                          // report the hit
window.__404less.suggest().then(d => window.__404less.render(d.suggestions, d.home));

Privacy

Runs only on pages it detects as a 404. On every other page it exits immediately.
Sends the URL (fragment stripped), the referrer and the user agent. No cookies, no fingerprinting, no third parties.
Hits are rate-limited per site at the edge and pruned after 90 days by default.