quartz/docs/layout-components.md

title
Higher-Order Layout Components

Quartz provides several higher-order components that help with layout composition and responsive design. These components wrap other components to add additional functionality or modify their behavior.

Most common use cases can be configured directly in quartz.config.yaml using layout properties. For advanced scenarios requiring custom logic, you can use the TS override approach in quartz.ts.

Flex Component

The Flex component creates a flexible box layout that can arrange child components in various ways. It's particularly useful for creating responsive layouts and organizing components in rows or columns.

YAML Configuration

In YAML, flex layouts are created using groups. Define a group in the top-level layout.groups section, then assign plugins to that group via their layout.group property:

plugins:
  - source: github:quartz-community/search
    enabled: true
    layout:
      position: left
      priority: 20
      group: toolbar
      groupOptions:
        grow: true # Search will grow to fill available space
  - source: github:quartz-community/darkmode
    enabled: true
    layout:
      position: left
      priority: 30
      group: toolbar # Darkmode keeps its natural size
  - source: github:quartz-community/reader-mode
    enabled: true
    layout:
      position: left
      priority: 35
      group: toolbar

layout:
  groups:
    toolbar:
      direction: row
      gap: 0.5rem

The groupOptions field on each plugin entry supports the following flex item properties:

Option	Type	Description
grow	boolean	Whether the component should grow to fill available space
shrink	boolean	Whether the component should shrink if needed
basis	string	Initial main size of the component (e.g., "200px")
order	number	Order in the flex container
align	"start" | "end" | "center" | "stretch"	Cross-axis alignment
justify	"start" | "end" | "center" | "between" | "around"	Main-axis alignment

The top-level layout.groups section configures the flex container itself:

Option	Type	Description
direction	"row" | "row-reverse" | "column" | "column-reverse"	Flex direction
wrap	"nowrap" | "wrap" | "wrap-reverse"	Flex wrap behavior
gap	string	Gap between flex items (e.g., "0.5rem")

TS Override

For full programmatic control, use the Component.Flex() wrapper in quartz.ts:

Component.Flex({
  components: [
    {
      Component: Plugin.Search(),
      grow: true, // Search will grow to fill available space
    },
    { Component: Plugin.Darkmode() }, // Darkmode keeps its natural size
  ],
  direction: "row",
  gap: "1rem",
})

type FlexConfig = {
  components: {
    Component: QuartzComponent
    grow?: boolean
    shrink?: boolean
    basis?: string
    order?: number
    align?: "start" | "end" | "center" | "stretch"
    justify?: "start" | "end" | "center" | "between" | "around"
  }[]
  direction?: "row" | "row-reverse" | "column" | "column-reverse"
  wrap?: "nowrap" | "wrap" | "wrap-reverse"
  gap?: string
}

[!note] Overriding behavior Components inside Flex get an additional CSS class flex-component that adds the display: flex property. If you want to override this behavior, you can add a display property to the component's CSS class in your custom CSS file.

.flex-component {
  display: block; // or any other display type
}

MobileOnly / DesktopOnly Components

These components control whether a plugin is visible on mobile or desktop devices. This is useful for creating responsive layouts where certain components should only appear on specific screen sizes.

YAML Configuration

In YAML, use the display property on a plugin's layout entry:

plugins:
  - source: github:quartz-community/table-of-contents
    enabled: true
    layout:
      position: right
      priority: 20
      display: desktop-only # Only visible on desktop

Available display values:

Value	Description
all	Visible on all screen sizes (default)
mobile-only	Only visible on mobile devices
desktop-only	Only visible on desktop devices

TS Override

For the TS override approach, use Component.MobileOnly() or Component.DesktopOnly() wrappers:

Component.MobileOnly(Component.Spacer())

Component.DesktopOnly(Plugin.TableOfContents())

ConditionalRender Component

The ConditionalRender component conditionally renders a plugin based on page properties. This is useful for creating dynamic layouts where components should only appear under certain conditions.

YAML Configuration

In YAML, use the condition property on a plugin's layout entry. Quartz provides several built-in condition presets:

plugins:
  - source: github:quartz-community/breadcrumbs
    enabled: true
    layout:
      position: beforeBody
      priority: 5
      condition: not-index # Hide breadcrumbs on the root index page

Available built-in conditions:

Condition	Description
not-index	Only render when the page is not the root index.md
has-tags	Only render when the page has tags in its frontmatter
has-backlinks	Only render when the page has backlinks
has-toc	Only render when the page has a table of contents

TS Override

For custom conditions that aren't covered by the built-in presets, use Component.ConditionalRender() in quartz.ts:

Component.ConditionalRender({
  component: Plugin.Search(),
  condition: (props) => props.displayClass !== "fullpage",
})

type ConditionalRenderConfig = {
  component: QuartzComponent
  condition: (props: QuartzComponentProps) => boolean
}

Tip

You can also register custom conditions for use in YAML by calling registerCondition() in a plugin's initialization code. See making plugins for more details.