#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>
<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>
<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-prefetchtriggers 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"anddownloadbecome plain anchors the router ignores.target="_blank"auto-addsrel="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>.svgin the project root (local, no network) orset:namefrom the Iconify API (e.g.lucide:heart). - Local SVGs keep their own
viewBox(fallback0 0 24 24); user attributes override defaults. - The icon is
1emsquare, so it scales with the surrounding text. Passsize={24}(orwidth/height) to change it. - Paint comes from the source: a solid icon (
<svg fill="currentColor">) keeps its fill, an outline one keeps itsstroke. An icon that sets no paint at all is drawn as a 2pxcurrentColoroutline. - SVG markup is sanitized before embedding: scripts,
<foreignObject>,<iframe>/<object>/<embed>, comments,on*/javascript:/data:attributes, SMILset/animatethat 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
srcsetat breakpoints (640/768/1024/1280/original width) for both codecs, plussizes. - CLS mitigation -
width/heightattributes andaspect-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-imageuntil the real image loads. - Loading -
loading="lazy"by default;priorityforceseager+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