Skip to main content
Quartz uses a component-based architecture to build your static site. Components are TypeScript/Preact functions that control how your content is rendered and displayed.

​
What are Components?

Components in Quartz are modular, reusable pieces that make up your site’s layout and functionality. Each component is responsible for rendering a specific part of your site, such as navigation, search, or content display.

​
Component Architecture

All Quartz components follow a consistent pattern defined by the QuartzComponent type:
quartz/components/types.ts
export type QuartzComponentProps = {
  ctx: BuildCtx
  externalResources: StaticResources
  fileData: QuartzPluginData
  cfg: GlobalConfiguration
  children: (QuartzComponent | JSX.Element)[]
  tree: Node
  allFiles: QuartzPluginData[]
  displayClass?: "mobile-only" | "desktop-only"
} & JSX.IntrinsicAttributes & {
    [key: string]: any
  }

export type QuartzComponent = ComponentType<QuartzComponentProps> & {
  css?: StringResource
  beforeDOMLoaded?: StringResource
  afterDOMLoaded?: StringResource
}
Each component can optionally include:
  • CSS styles - Component-specific styling
  • beforeDOMLoaded script - JavaScript that runs before the DOM is ready
  • afterDOMLoaded script - JavaScript that runs after the DOM is loaded

​
Component Types

Quartz components fall into several categories:
Components that define the structure and layout of your pages:
  • Head - HTML head metadata
  • PageTitle - Site title in the header
  • Header - Custom header content
  • Footer - Site footer with links
  • Spacer - Adds vertical spacing
Components that display page content and metadata:
  • Content - Main page content
  • ArticleTitle - Article heading
  • ContentMeta - Date and reading time
  • TagList - Page tags
  • Backlinks - Pages linking to current page
  • RecentNotes - Latest content list
Components that add functionality or control display:
  • Darkmode - Theme toggle button
  • ReaderMode - Reader mode toggle
  • Comments - Giscus comments integration
  • DesktopOnly - Show only on desktop
  • MobileOnly - Show only on mobile
  • Flex - Flexbox layout wrapper
  • ConditionalRender - Conditionally display components
Full-page templates for different content types:
  • Content - Single page display
  • TagContent - Tag listing page
  • FolderContent - Folder listing page
  • NotFound - 404 error page

​
Component Configuration

Components are configured in your quartz.layout.ts file. Quartz provides two main layout configurations:

​
Shared Layout

Components that appear on every page:
quartz.layout.ts
export const sharedPageComponents: SharedLayout = {
  head: Component.Head(),
  header: [],
  afterBody: [],
  footer: Component.Footer({
    links: {
      GitHub: "https://github.com/jackyzha0/quartz",
      "Discord Community": "https://discord.gg/cRFFHYye7t",
    },
  }),
}

​
Page Layout

Components positioned in different areas of your pages:
quartz.layout.ts
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.Breadcrumbs(),
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TagList(),
  ],
  left: [
    Component.PageTitle(),
    Component.MobileOnly(Component.Spacer()),
    Component.Search(),
    Component.Darkmode(),
    Component.Explorer(),
  ],
  right: [
    Component.Graph(),
    Component.DesktopOnly(Component.TableOfContents()),
    Component.Backlinks(),
  ],
}

​
Layout Areas

Components can be placed in five main areas:

head

HTML <head> section - metadata, scripts, and styles

header

Top of every page - typically navigation or branding

beforeBody

Above main content - breadcrumbs, title, metadata

left

Left sidebar - navigation, search, explorer

right

Right sidebar - table of contents, graph, backlinks

footer

Bottom of every page - copyright, links

​
Component Constructor Pattern

Most Quartz components use a constructor pattern that allows configuration: 
export default ((userOpts?: Partial<Options>) => {
  const opts: Options = { ...defaultOptions, ...userOpts }
  
  const MyComponent: QuartzComponent = (props: QuartzComponentProps) => {
    // Component implementation
    return <div>...</div>
  }
  
  MyComponent.css = style
  MyComponent.afterDOMLoaded = script
  
  return MyComponent
}) satisfies QuartzComponentConstructor
This pattern enables:
  • Default options that can be overridden
  • Type-safe configuration
  • Consistent API across all components

​
Props and Context

Components receive rich context through their props:
​
fileData
QuartzPluginData
Current page data including frontmatter, content, and metadata
​
allFiles
QuartzPluginData[]
All files in your vault for cross-referencing
​
cfg
GlobalConfiguration
Global Quartz configuration from quartz.config.ts
​
displayClass
string
Optional CSS class for responsive display (mobile-only or desktop-only)
​
tree
Node
AST representation of the current page content

​
Next Steps

Built-in Components

Explore all available components and their configuration options

Custom Components

Learn how to create your own custom components

Build docs developers (and LLMs) love

Get started for freeTalk to us