{"route":"/en-US-v0.14.1/reference/introspection/counter/","title":"Counter","description":"Documentation for the Counter type.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"accessing","name":"Accessing","children":[]},{"id":"displaying","name":"Displaying","children":[]},{"id":"modifying","name":"Modifying","children":[]},{"id":"page-counter","name":"Page counter","children":[]},{"id":"custom-counters","name":"Custom counters","children":[]},{"id":"how-to-step","name":"How to step","children":[]},{"id":"time-travel","name":"Time travel","children":[]},{"id":"other-state","name":"Other State","children":[]},{"id":"constructor","name":"Constructor","children":[{"id":"constructor-key","name":"key","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-get","name":"Get","children":[]},{"id":"definitions-display","name":"Display","children":[{"id":"definitions-display-numbering","name":"numbering","children":[]},{"id":"definitions-display-both","name":"both","children":[]}]},{"id":"definitions-at","name":"At","children":[{"id":"definitions-at-selector","name":"selector","children":[]}]},{"id":"definitions-final","name":"Final","children":[]},{"id":"definitions-step","name":"Step","children":[{"id":"definitions-step-level","name":"level","children":[]}]},{"id":"definitions-update","name":"Update","children":[{"id":"definitions-update-update","name":"update","children":[]}]}]}],"body":{"kind":"type","content":{"name":"counter","title":"Counter","keywords":[],"oneliner":"Counts through pages, elements, and more.","details":"

Counts through pages, elements, and more.

\n

With the counter function, you can access and modify counters for pages,\nheadings, figures, and more. Moreover, you can define custom counters for\nother things you want to count.

\n

Since counters change throughout the course of the document, their current\nvalue is contextual. It is recommended to read the chapter on context\nbefore continuing here.

\n

Accessing a counter

\n

To access the raw value of a counter, we can use the get\nfunction. This function returns an array: Counters can have multiple\nlevels (in the case of headings for sections, subsections, and so on), and\neach item in the array corresponds to one level.

\n
#set heading(numbering: "1.")\n\n= Introduction\nRaw value of heading counter is\n#context counter(heading).get()\n
\"Preview\"
\n

Displaying a counter

\n

Often, we want to display the value of a counter in a more human-readable\nway. To do that, we can call the display function on\nthe counter. This function retrieves the current counter value and formats\nit either with a provided or with an automatically inferred numbering.

\n
#set heading(numbering: "1.")\n\n= Introduction\nSome text here.\n\n= Background\nThe current value is: #context {\n  counter(heading).display()\n}\n\nOr in roman numerals: #context {\n  counter(heading).display("I")\n}\n
\"Preview\"
\n

Modifying a counter

\n

To modify a counter, you can use the step and update methods:

\n\n

The heading counter is stepped before the heading is displayed, so\nAnalysis gets the number seven even though the counter is at six after the\nsecond update.

\n
#set heading(numbering: "1.")\n\n= Introduction\n#counter(heading).step()\n\n= Background\n#counter(heading).update(3)\n#counter(heading).update(n => n * 2)\n\n= Analysis\nLet's skip 7.1.\n#counter(heading).step(level: 2)\n\n== Analysis\nStill at #context {\n  counter(heading).display()\n}\n
\"Preview\"
\n

Page counter

\n

The page counter is special. It is automatically stepped at each pagebreak.\nBut like other counters, you can also step it manually. For example, you\ncould have Roman page numbers for your preface, then switch to Arabic page\nnumbers for your main content and reset the page counter to one.

\n
#set page(numbering: "(i)")\n\n= Preface\nThe preface is numbered with\nroman numerals.\n\n#set page(numbering: "1 / 1")\n#counter(page).update(1)\n\n= Main text\nHere, the counter is reset to one.\nWe also display both the current\npage and total number of pages in\nArabic numbers.\n
\"Preview\"Preview
\n

Custom counters

\n

To define your own counter, call the counter function with a string as a\nkey. This key identifies the counter globally.

\n
#let mine = counter("mycounter")\n#context mine.display() \\\n#mine.step()\n#context mine.display() \\\n#mine.update(c => c * 3)\n#context mine.display()\n
\"Preview\"
\n

How to step

\n

When you define and use a custom counter, in general, you should first step\nthe counter and then display it. This way, the stepping behaviour of a\ncounter can depend on the element it is stepped for. If you were writing a\ncounter for, let's say, theorems, your theorem's definition would thus first\ninclude the counter step and only then display the counter and the theorem's\ncontents.

\n
#let c = counter("theorem")\n#let theorem(it) = block[\n  #c.step()\n  *Theorem #context c.display():*\n  #it\n]\n\n#theorem[$1 = 1$]\n#theorem[$2 < 3$]\n
\"Preview\"
\n

The rationale behind this is best explained on the example of the heading\ncounter: An update to the heading counter depends on the heading's level. By\nstepping directly before the heading, we can correctly step from 1 to\n1.1 when encountering a level 2 heading. If we were to step after the\nheading, we wouldn't know what to step to.

\n

Because counters should always be stepped before the elements they count,\nthey always start at zero. This way, they are at one for the first display\n(which happens after the first step).

\n

Time travel

\n

Counters can travel through time! You can find out the final value of the\ncounter before it is reached and even determine what the value was at any\nparticular location in the document.

\n
#let mine = counter("mycounter")\n\n= Values\n#context [\n  Value here: #mine.get() \\\n  At intro: #mine.at(<intro>) \\\n  Final value: #mine.final()\n]\n\n#mine.update(n => n + 3)\n\n= Introduction <intro>\n#lorem(10)\n\n#mine.step()\n#mine.step()\n
\"Preview\"
\n

Other kinds of state

\n

The counter type is closely related to state type. Read its\ndocumentation for more details on state management in Typst and why it\ndoesn't just use normal variables for counters.

","constructor":{"path":[],"name":"counter","title":"Construct","keywords":[],"oneliner":"Create a new counter identified by a key.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Create a new counter identified by a key.

"}],"self":false,"params":[{"name":"key","details":[{"kind":"html","content":"

The key that identifies this counter globally.

\n"}],"types":["str","label","selector","location","function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["counter"],"scope":[]},"scope":[{"path":["counter"],"name":"get","title":"Get","keywords":[],"oneliner":"Retrieves the value of the counter at the current location.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Retrieves the value of the counter at the current location. Always\nreturns an array of integers, even if the counter has just one number.

\n

This is equivalent to counter.at(here()).

"}],"self":true,"params":[],"returns":["int","array"],"scope":[]},{"path":["counter"],"name":"display","title":"Display","keywords":[],"oneliner":"Displays the current value of the counter with a numbering and returns the formatted output.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Displays the current value of the counter with a numbering and returns\nthe formatted output.

"}],"self":true,"params":[{"name":"numbering","details":[{"kind":"html","content":"

A numbering pattern or a function, which specifies how\nto display the counter. If given a function, that function receives\neach number of the counter as a separate argument. If the amount of\nnumbers varies, e.g. for the heading argument, you can use an\nargument sink.

\n

If this is omitted or set to auto, displays the counter with the\nnumbering style for the counted element or with the pattern\n"1.1" if no such style exists.

"}],"types":["auto","str","function"],"strings":[],"default":"auto","positional":true,"named":false,"required":false,"variadic":false,"settable":false},{"name":"both","details":[{"kind":"html","content":"

If enabled, displays the current and final top-level count together.\nBoth can be styled through a single numbering pattern. This is used\nby the page numbering property to display the current and total\nnumber of pages when a pattern like "1 / 1" is given.

"}],"types":["bool"],"strings":[],"default":"false","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["any"],"scope":[]},{"path":["counter"],"name":"at","title":"At","keywords":[],"oneliner":"Retrieves the value of the counter at the given location.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Retrieves the value of the counter at the given location. Always returns\nan array of integers, even if the counter has just one number.

\n

The selector must match exactly one element in the document. The most\nuseful kinds of selectors for this are labels and\nlocations.

"}],"self":true,"params":[{"name":"selector","details":[{"kind":"html","content":"

The place at which the counter's value should be retrieved.

"}],"types":["label","selector","location","function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["int","array"],"scope":[]},{"path":["counter"],"name":"final","title":"Final","keywords":[],"oneliner":"Retrieves the value of the counter at the end of the document.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Retrieves the value of the counter at the end of the document. Always\nreturns an array of integers, even if the counter has just one number.

"}],"self":true,"params":[],"returns":["int","array"],"scope":[]},{"path":["counter"],"name":"step","title":"Step","keywords":[],"oneliner":"Increases the value of the counter by one.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Increases the value of the counter by one.

\n

The update will be in effect at the position where the returned content\nis inserted into the document. If you don't put the output into the\ndocument, nothing happens! This would be the case, for example, if you\nwrite let _ = counter(page).step(). Counter updates are always\napplied in layout order and in that case, Typst wouldn't know when to\nstep the counter.

"}],"self":true,"params":[{"name":"level","details":[{"kind":"html","content":"

The depth at which to step the counter. Defaults to 1.

"}],"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["content"],"scope":[]},{"path":["counter"],"name":"update","title":"Update","keywords":[],"oneliner":"Updates the value of the counter.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Updates the value of the counter.

\n

Just like with step, the update only occurs if you put the resulting\ncontent into the document.

"}],"self":true,"params":[{"name":"update","details":[{"kind":"html","content":"

If given an integer or array of integers, sets the counter to that\nvalue. If given a function, that function receives the previous\ncounter value (with each number as a separate argument) and has to\nreturn the new value (integer or array).

"}],"types":["int","array","function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["content"],"scope":[]}]}}}