Skip to main content
Use the Variation component to show or hide content based on the variation a reader selects from the variation dropdown. Variations are useful when the same page needs to describe a different audience, region, plan tier, or deployment target without duplicating the page.
Variations are available on the Willow theme. On other themes, the configuration and switcher are ignored.

​
Configure variations

Add a variations object to your docs.json with the options you want readers to switch between. The first option is the default.
docs.json
​
array
required
Variation options in display order. The first option is the default. Each option requires:
  • id: A stable, unique identifier used in the Variation component and URL.
  • label: The display name shown in the variation dropdown.
When variations is configured, a Variation dropdown appears above the existing view switcher in the table of contents sidebar, side panels, changelog filters, and inline on mobile.

​
Use the component

Wrap conditional content in a Variation component and set is to the option id that should reveal it. Content outside a Variation block always shows.
To share content between multiple variations, pass an array to is:

​
How readers switch variations

  • Readers pick a variation from the dropdown in the table of contents sidebar.
  • The selection is saved in local storage per project, so readers keep their variation as they move between pages.
  • The current variation is reflected in the URL as ?variation=<id>, which makes it easy to share a link to a specific variation.

​
Table of contents behavior

Headings inside a Variation block are automatically filtered from the table of contents when a different variation is active. Headings outside any Variation block always appear. Nested Variation blocks intersect: an inner block only shows when its is value is compatible with every enclosing block.

​
Properties

​
string or string[]
required
The variation id (or array of ids) that should reveal the wrapped content. Ids must match an option defined in variations.options in docs.json.