{"route":"/en-US-v0.14.1/reference/styling/","title":"Styling","description":"All concepts needed to style your document with Typst.","part":null,"outline":[{"id":"set-rules","name":"Set rules","children":[]},{"id":"show-rules","name":"Show rules","children":[]}],"body":{"kind":"html","content":"

Styling

\n

Typst includes a flexible styling system that automatically applies styling of\nyour choice to your document. With set rules, you can configure basic\nproperties of elements. This way, you create most common styles. However, there\nmight not be a built-in property for everything you wish to do. For this reason,\nTypst further supports show rules that can completely redefine the appearance\nof elements.

\n

Set rules

\n

With set rules, you can customize the appearance of elements. They are written\nas a function call to an element\nfunction preceded by the set keyword (or\n#set in markup). Only optional parameters of that function can be provided\nto the set rule. Refer to each function's documentation to see which parameters\nare optional. In the example below, we use two set rules to change the\nfont family and heading numbering.

\n
#set heading(numbering: "I.")\n#set text(\n  font: "New Computer Modern"\n)\n\n= Introduction\nWith set rules, you can style\nyour document.\n
\"Preview\"
\n

A top level set rule stays in effect until the end of the file. When nested\ninside of a block, it is only in effect until the end of that block. With a\nblock, you can thus restrict the effect of a rule to a particular segment of\nyour document. Below, we use a content block to scope the list styling to one\nparticular list.

\n
This list is affected: #[\n  #set list(marker: [--])\n  - Dash\n]\n\nThis one is not:\n- Bullet\n
\"Preview\"
\n

Sometimes, you'll want to apply a set rule conditionally. For this, you can use\na set-if rule.

\n
#let task(body, critical: false) = {\n  set text(red) if critical\n  [- #body]\n}\n\n#task(critical: true)[Food today?]\n#task(critical: false)[Work deadline]\n
\"Preview\"
\n

Show rules

\n

With show rules, you can deeply customize the look of a type of element. The\nmost basic form of show rule is a show-set rule. Such a rule is written as the\nshow keyword followed by a selector, a colon and then a set rule. The most\nbasic form of selector is an element function.\nThis lets the set rule only apply to the selected element. In the example below,\nheadings become dark blue while all other text stays black.

\n
#show heading: set text(navy)\n\n= This is navy-blue\nBut this stays black.\n
\"Preview\"
\n

With show-set rules you can mix and match properties from different functions to\nachieve many different effects. But they still limit you to what is predefined\nin Typst. For maximum flexibility, you can instead write a transformational\nshow rule that defines how to format an element from scratch. To write such a\nshow rule, replace the set rule after the colon with an arbitrary function.\nThis function receives the element in question and can return arbitrary content.\nThe function is often defined inline as it => .. using the\nunnamed function syntax. The function's parameter is\ntypically named it by convention.

\n

The available fields on the element passed to the function\nmatch the parameters of the respective element function. Below, we define a show\nrule that formats headings for a fantasy encyclopedia.

\n

The show rule itself adds tilde characters around the title (these must be\nescaped with a backslash because otherwise they would indicate a non-breaking\nspace), emphasizes the title with italics, and then displays the heading counter\nafter the title.

\n

For this example, we also wanted center alignment and a different font. While we\ncould've added these set rules into the existing show rule, we instead added\nthem as separate show-set rules. This is good practice because now these rules\ncan still be overridden by later show-set rules in the document, keeping styling\ncomposable. In contrast, set rules within a transformational show rule would not\nbe overridable anymore.

\n
#set heading(numbering: "(I)")\n#show heading: set align(center)\n#show heading: set text(font: "Inria Serif")\n#show heading: it => block[\n  \\~\n  #emph(it.body)\n  #counter(heading).display(it.numbering)\n  \\~\n]\n\n= Dragon\nWith a base health of 15, the dragon is the most\npowerful creature.\n\n= Manticore\nWhile less powerful than the dragon, the manticore\ngets extra style points.\n
\"Preview\"
\n

Like set rules, show rules are in effect until the end of the current block or\nfile.

\n

Instead of a function, the right-hand side of a show rule can also take a\nliteral string or content block that should be directly substituted for the\nelement. And apart from a function, the left-hand side of a show rule can also\ntake a number of other selectors that define what to apply the transformation\nto:

\n\n
#show "Project": smallcaps\n#show "badly": "great"\n\nWe started Project in 2019\nand are still working on it.\nProject is progressing badly.\n
\"Preview\"
"}}