Phuriwaj

Quartz Custom Component Development

Quartz Custom Component Development

How to write, register, and configure custom TSX components in a Quartz digital garden.

Why / When to Use

When the built-in Quartz components don’t cover a need — e.g. a note counter, custom header, tag cloud, or series navigator. Components are plain TSX with an optional CSS string and optional config options.

Core Concept / Commands

Minimal component skeleton

// quartz/components/YourComponent.tsx
import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
 
export default (() => {
  function YourComponent() {
    return <p class="red-text">Example Component</p>
  }
 
  YourComponent.css = `
    p.red-text {
      color: red;
    }
  `
 
  return YourComponent
}) satisfies QuartzComponentConstructor

Three things: JSX function, optional .css string, export default.

Component with config options

interface Options {
  showCount: boolean
}
const defaultOptions: Options = { showCount: true }
 
export default ((userOpts?: Options) => {
  const opts = { ...defaultOptions, ...userOpts }
 
  function YourComponent({ allFiles, displayClass }: QuartzComponentProps) {
    const count = allFiles.length
    return (
      <div class={`your-component ${displayClass}`}>
        {opts.showCount && <span class="count">{count}</span>}
      </div>
    )
  }
 
  YourComponent.css = `...`
  return YourComponent
}) satisfies QuartzComponentConstructor
  • allFiles — metadata for all parsed files (useful for counts, listings, cross-file queries)
  • displayClass — utility class for mobile/desktop rendering preference

Registration — two required steps

Step 1 — Export from index:

// quartz/components/index.ts
export { default as YourComponent } from "./YourComponent"

Step 2 — Add to layout:

// quartz.layout.ts
import * as Component from "./quartz/components"
 
// Use in layout:
Component.YourComponent()
// Or with options:
Component.YourComponent({ showCount: false })

Key Options / Variants

Best reference files to copy from

FileWhat it teaches
quartz/components/Footer.tsxSimplest built-in — best starting template
quartz/components/TagList.tsxReading frontmatter, rendering links
quartz/components/Backlinks.tsxReading allFiles, filtering, listing
quartz/components/ContentMeta.tsxDates, reading time, metadata display
quartz/components/Explorer.tsxComplex component with JavaScript

Fastest start

cp ~/projects/quartz/quartz/components/Footer.tsx \
   ~/projects/quartz/quartz/components/GardenHero.tsx

Gut the JSX, write your own. The scaffold (types, export pattern) is already correct.

Gotchas

  • Use class not className in Quartz TSX (it uses Preact, not React)
  • CSS is scoped to the component via the .css string property — no separate file needed
  • allFiles is read-only metadata — it doesn’t give you file contents, just frontmatter + graph data
  • Both registration steps are required; missing either one silently omits the component

Source

Conversation “Note Taking - Hugo&Quartz” — 2026-06-01