Styling pages

Each page Format renders is isolated from the others. A Layout's CSS applies only to the pages that Layout produces, Format's base styles load before yours, and every page exposes a host element you target with :host().

How a page is structured

A page is a host element holding that page's content. Format writes data attributes onto the host that describe the page, then fills the page with the Layout's stylesheets and content:

<div class="host" data-layout-id="invoice" data-page-number="1" data-first-page>
	#shadow-root (closed)
		<!-- the Layout's stylesheets -->
		<!-- the Layout's content for this page -->
</div>

Target an individual page by pairing the :host() selector with the attributes Format writes per page. The data-layout-id attribute carries the id of the Layout that produced the page, so :host([data-layout-id="invoice"]) styles every page that Layout produces; data-page-number, data-first-page, data-last-page, data-even-page, and data-odd-page narrow to one page or a class of pages. Examples follow below.

Attaching CSS

How CSS gets into the document, and how it's scoped, depends on how you author.

With Studio

You import stylesheets from your document's entry point. Studio bundles them all (CSS, SASS, Linaria, CSS Modules, Tailwind, and the other options under Styling in Studio) and injects the compiled result into every Layout in the document.

import { Document } from '@format.dev/react'

import './styles.css'

export default function InvoiceDocument() {
  return (
    <Document title="Invoice">
      {/* Your content goes here */}
    </Document>
  )
}

<script setup lang="ts">
import { Document } from '@format.dev/vue'
</script>

<style>
@import './styles.css';
</style>

<template>
  <Document title="Invoice">
    <!-- Your content goes here -->
  </Document>
</template>

export { default } from './index.html'
import './styles.css'

Because the bundle goes into every Layout, your CSS is effectively global across the document: a rule in cover.css applies to every Layout, even if you only intended it for the cover. Class collisions across Layouts are a real concern. Namespace your selectors, use CSS Modules, or scope a rule to one Layout with :host([data-layout-id="invoice"]) .title { ... } where overlap is possible.

Without Studio

When you're authoring the document HTML directly, by hand or from a server template, you control where each stylesheet lands. A <style> block or <link rel="stylesheet"> inside a Layout's <template> applies only to the pages that Layout produces, so per-Layout scoping is automatic. Use <link rel="stylesheet"> when several Layouts share one external file.

<template data-type="layout" data-id="invoice" data-width="793.71px" data-height="1122.52px">
  <style>
    h1 { font-size: 32px; }
    p  { line-height: 1.6; }
  </style>

  <link rel="stylesheet" href="/shared.css" />

  <!-- scaffolding... -->
</template>

Format resolves a <link rel="stylesheet"> against your assets bundle and inlines its CSS into that Layout's pages. For the wider picture of producing Format documents without Studio, see Building documents.

Document-level global styles

To share styles across every Layout, place a <style> or <link rel="stylesheet"> directly under the <Document>, outside any Layout. Format applies these to every page as global styles, in a cascade layer (@layer format-document) that each Layout's own styles override. They act as document-wide defaults you can still tune per Layout.

<template data-type="document" data-title="Invoice">
  <style>
    :host { color: #1a1a1a; line-height: 1.5; }
  </style>

  <template data-type="layout" data-id="cover" data-width="595px" data-height="842px">
    <!-- inherits the document-level defaults; can override any of them -->
  </template>
  <template data-type="layout" data-id="body" data-width="595px" data-height="842px">
    <!-- ...same defaults... -->
  </template>
</template>

Global @font-face

Using @font-face is the one exception to per-Layout scoping. Format applies every font declaration across the document, so a font declared anywhere is available on every page, no matter which Layout rendered it and regardless of how you authored.

The base layer

Before your styles run, every page loads a base layer Format controls. It does roughly what a CSS reset does: normalizes box-sizing, makes images render predictably, and sets sensible typographic defaults on the page. Your own rules sit inside a higher cascade layer (@layer format-layout), so they override the base layer. Document-level global styles sit between the two, in @layer format-document, so a Layout's own styles win over a document-wide default.

The page starts with a white background, an accessible line-height, and Format's font-family variables. Override these in your Layout's CSS for a non-white background or different typography.

For a transparent PDF, set background: transparent on :host.

Targeting a page with :host()

You target the page itself with the :host() functional selector. Pair it with the host's data attributes to style one page differently from the next:

/* applies to every page */
:host { background: lightgrey; }

/* first page only */
:host([data-first-page]) header { display: none; }

/* last page only */
:host([data-last-page]) { background: #fdf8ef; }

/* a single page, by number */
:host([data-page-number="3"]) footer { display: none; }

Plain :host is the place for page-level defaults like a background color or a flex layout. Adding a data attribute narrows it: data-first-page for cover-page treatments, data-last-page for finale styling, data-page-number="N" for a single page by number.

Page numbers and page count

Page numbers are the most common per-page need. Place <span data-type="page-number"> and <span data-type="page-count"> in a header or footer, and Format fills them in with the current page and total. All our SDKs provide <PageNumber /> and <PageCount /> components that compile to these. To change the format (Roman numerals, letters, and so on), set --page-counter-style on :host. It accepts any valid CSS <counter-style> name, including custom @counter-style names.

DOM contract

The full set of per-page state Format publishes: the CSS custom properties and data attributes it writes onto each page, plus the base defaults you can override.

CSS custom properties

Base CSS defaults

Variables Format's base stylesheet initializes with a default. Override on :host from your Layout's CSS to change behavior.

Data attributes

Related

• Building documents
• Scaffolding
• Pagination
• Fonts
• Margins and page padding