Krate Docs

#Built-in Components

Script, Style, Link, Icon, and Image components provided by Krate.

Krate provides a set of built-in components that are recognized by the compiler by name - they work without any import:

Component Usage Description
<Head> <Head><title>...</title></Head> Injects content into <head>
<Script> <Script src="/app.js"/> or <Script>{inline}</Script> External or inline script in <body>
<Style> <Style>{css}</Style> Inline <style> in <head>
<Link> <Link href="/about">About</Link> SPA-enabled <a>
<Icon> <Icon name="lucide:menu"/> SVG from Iconify API (compile-time) or icons/
<Image> <Image src="/photo.jpg" width={800}/> Responsive <picture> (compile-time)
<Head>
  <title>My Page</title>
  <meta name="description" content="A cool page" />
</Head>

Content inside <Head> is hoisted into the page's <head>. This works at any component depth, including inside layouts and plugin-generated pages.

<Head> and the other built-in tags (<Link>, <Image>, <Script>, <Style>, <Icon>, <Suspense>, <SyntaxHighlight>) are globals in every component module: pages, layouts, components imported by an SSR page, and components that run as islands. import { Head } from "@krate/runtime" works too and names the same tag.

When a page has several <Head> blocks (a component's, a nested component's, the page's own), the last <title> and the last <meta name>, <meta property> (except repeated og:image-style properties), <link rel="canonical"> and <base> win, the way they do for pages rendered per request. A page's head wins over its layouts'. Components that are not interactive contribute their tags in document order; the tags of a component with state or event handlers are collected after them, so give a page one <title> rather than relying on the order of two. A component rendered inside <Head> never hydrates: its markup is not in the page body, so a page whose only stateful component sits in <Head> ships no JavaScript.

#Document attributes

Lowercase <html> and <body> elements inside <Head> set attributes on the document's own <html> and <body> instead of rendering anything:

export default function RootLayout({ children }) {
  return (
    <>
      <Head>
        <html lang="fr" className="dark" />
        <body className="font-sans antialiased" />
      </Head>
      {children}
    </>
  );
}

Attributes merge in this order, each source replacing single attributes of the one before: site.htmlAttributes / site.bodyAttributes in the config, the layouts' <Head>, the page's <Head> and, for lang, the page's export const lang. Values are escaped. In a page that renders per request the values may be dynamic (<html className={theme} /> after an await); a static page takes the build-time value. Client-side navigation applies the attributes that differ between the old and the new page and leaves ones a script set at runtime (a theme class) alone. A <Head> inside a streamed Suspense region cannot change the document attributes, because they are already sent. Plugins see <html> and <body> elements in the headHTML their hooks receive and can add their own.

A <title>, <meta> or <link> rendered outside <Head> is also placed in the <head>, following React 19's document metadata rules: a reactive <title> updates document.title, and metadata inside <svg>, with an itemProp, or inside a conditional branch or list item stays in place (see the React compatibility guide).

#export const metadata

A page can also declare its head tags as a literal metadata object, the way a Next.js page does:

export const metadata = {
  title: "Pricing",
  description: "Plans and pricing",
  alternates: { canonical: "https://example.com/pricing" },
  openGraph: { title: "Pricing", images: ["/og/pricing.png"] },
  twitter: { card: "summary_large_image" },
};

export default function Pricing() {
  return <main>...</main>;
}

The build turns it into the document <title>, description, keywords, robots, theme-color, canonical and icon links, and the og:* and twitter:* tags. An explicit <Head> on the page wins over metadata for the same tag, and metadata wins over a layout's head. generateMetadata, computed values, and metadata in layouts work too: see Metadata.

#<Script>

<Script src="/app.js" />
<Script>{`console.log('inline');`}</Script>

External scripts are emitted as <script src> in the body; inline children are written raw (never HTML-escaped).

#<Style>

<Style>{`.my-class { color: red; }`}</Style>

Inline CSS is captured into <head>.

<Link> renders a real <a> wired for SPA navigation via initRouter:

<Link href="/about">About</Link>
<Link href="/faq" prefetch={false}>No prefetch</Link>
<Link href="/docs" replace>Replace history entry</Link>
<Link href="/blog" scroll={false}>No scroll-to-top</Link>
<Link href="https://example.com">External</Link>
<Link href="/new" target="_blank">New tab</Link>
<Link href="/pricing" basePath={false}>Outside the base path</Link>
  • Prefetching (default on) - data-prefetch triggers a prefetch on hover/focus (debounced) and on viewport entry (IntersectionObserver, rootMargin: 200px).
  • replace - swaps the history entry instead of pushing.
  • scroll - scrolls to top on forward navigation by default.
  • Hash links - href="/about#section" fetches the page then scrolls to the element.
  • Modified clicks - Cmd/Ctrl/Shift/Alt-click and middle-click are never intercepted.
  • External links - http(s)://, //, mailto:, tel:, #, target="_blank" and download become plain anchors the router ignores. target="_blank" auto-adds rel="noopener noreferrer".
  • Attributes - className (-> class), target, rel, title, id, aria-label, and other static attributes are forwarded.
  • Active link - after navigation, the link matching the current path gets aria-current="page".

#<Icon>

<Icon name="lucide:heart" />
<Icon name="menu" />          // from the local icons/ registry
  • Name resolution - icons/<name>.svg in the project root (local, no network) or set:name from the Iconify API (e.g. lucide:heart).
  • Local SVGs keep their own viewBox (fallback 0 0 24 24); user attributes override defaults.
  • The icon is 1em square, so it scales with the surrounding text. Pass size={24} (or width/height) to change it.
  • Paint comes from the source: a solid icon (<svg fill="currentColor">) keeps its fill, an outline one keeps its stroke. An icon that sets no paint at all is drawn as a 2px currentColor outline.
  • SVG markup is sanitized before embedding: scripts, <foreignObject>, <iframe>/<object>/<embed>, comments, on*/javascript:/data: attributes, SMIL set/animate that target a link, <style> that imports or fetches external files, and external <image> are stripped.
  • Fetched SVGs are cached on disk (.krate/cache/icons/); icon names are validated against [a-zA-Z0-9_.-] (max 64 chars).
  • An icon that is not in icons/ and cannot be fetched fails the build with KR8840 and the file and line of the <Icon>. Nothing about the failure is written into the page.

#<Image>

<Image
  src="/hero.jpg"        // resolved against public/
  width={800}            // display width (optional; intrinsic used if omitted)
  alt="Hero"
  loading="lazy"         // "lazy" (default) | "eager"
  priority               // eager + fetchpriority="high"
  quality={82}           // WebP/fallback quality (0-100)
  sizes="(max-width: 768px) 100vw, 50vw"
  placeholder="blur"     // "blur" (default) | "empty"
/>

<Image> compiles to a WebP-first <picture> at build time (pure-Go encoder, no cgo):

  • WebP + fallback - every variant is emitted twice: a <source type="image/webp"> (lossy WebP via a pure-Go encoder) and a <source> in the original codec (JPEG, or PNG when the source has transparency). The <img> falls back to the original file for browsers without <picture>.
  • Responsive - a srcset at breakpoints (640/768/1024/1280/original width) for both codecs, plus sizes.
  • CLS mitigation - width/height attributes and aspect-ratio:W/H (intrinsic ratio; width wins if props mismatch) reserve space.
  • Blur placeholder (LQIP) - a 16px box-blurred, base64 data-URI as the background-image until the real image loads.
  • Loading - loading="lazy" by default; priority forces eager + fetchpriority="high"; decoding="async" always set.
  • Output - variants written to .krate/cache/images/ and copied to <outDir>/_krate/images/ (served at /_krate/images/...).

Last updated: 2026-11-17

Contributors: Noinkin