{"route":"/en-US-v0.14.1/reference/layout/block/","title":"Block","description":"Documentation for the `block` function.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"examples","name":"Examples","children":[]},{"id":"parameters","name":"Parameters","children":[{"id":"parameters-width","name":"width","children":[]},{"id":"parameters-height","name":"height","children":[]},{"id":"parameters-breakable","name":"breakable","children":[]},{"id":"parameters-fill","name":"fill","children":[]},{"id":"parameters-stroke","name":"stroke","children":[]},{"id":"parameters-radius","name":"radius","children":[]},{"id":"parameters-inset","name":"inset","children":[]},{"id":"parameters-outset","name":"outset","children":[]},{"id":"parameters-spacing","name":"spacing","children":[]},{"id":"parameters-above","name":"above","children":[]},{"id":"parameters-below","name":"below","children":[]},{"id":"parameters-clip","name":"clip","children":[]},{"id":"parameters-sticky","name":"sticky","children":[]},{"id":"parameters-body","name":"body","children":[]}]}],"body":{"kind":"func","content":{"path":[],"name":"block","title":"Block","keywords":[],"oneliner":"A block-level container.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

A block-level container.

\n

Such a container can be used to separate content, size it, and give it a\nbackground or border.

\n

Blocks are also the primary way to control whether text becomes part of a\nparagraph or not. See the paragraph documentation\nfor more details.

\n

Examples

\n

With a block, you can give a background to content while still allowing it\nto break across multiple pages.

\n
#set page(height: 100pt)\n#block(\n  fill: luma(230),\n  inset: 8pt,\n  radius: 4pt,\n  lorem(30),\n)\n
\"Preview\"Preview
\n

Blocks are also useful to force elements that would otherwise be inline to\nbecome block-level, especially when writing show rules.

\n
#show heading: it => it.body\n= Blockless\nMore text.\n\n#show heading: it => block(it.body)\n= Blocky\nMore text.\n
\"Preview\"
"}],"self":false,"params":[{"name":"width","details":[{"kind":"html","content":"

The block's width.

"},{"kind":"example","content":{"body":"
#set align(center)\n#block(\n  width: 60%,\n  inset: 8pt,\n  fill: silver,\n  lorem(10),\n)\n
\"Preview\"
","title":null}}],"types":["auto","relative"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"height","details":[{"kind":"html","content":"

The block's height. When the height is larger than the remaining space\non a page and breakable is true, the\nblock will continue on the next page with the remaining height.

"},{"kind":"example","content":{"body":"
#set page(height: 80pt)\n#set align(center)\n#block(\n  width: 80%,\n  height: 150%,\n  fill: aqua,\n)\n
\"Preview\"Preview
","title":null}}],"types":["auto","relative","fraction"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"breakable","details":[{"kind":"html","content":"

Whether the block can be broken and continue on the next page.

"},{"kind":"example","content":{"body":"
#set page(height: 80pt)\nThe following block will\njump to its own page.\n#block(\n  breakable: false,\n  lorem(15),\n)\n
\"Preview\"Preview
","title":null}}],"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"fill","details":[{"kind":"html","content":"

The block's background color. See the\nrectangle's documentation for more details.

"}],"types":["none","color","gradient","tiling"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":[{"kind":"html","content":"

The block's border color. See the\nrectangle's documentation for more details.

"}],"types":["none","length","color","gradient","stroke","tiling","dictionary"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"radius","details":[{"kind":"html","content":"

How much to round the block's corners. See the\nrectangle's documentation for more details.

"}],"types":["relative","dictionary"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"inset","details":[{"kind":"html","content":"

How much to pad the block's content. See the\nbox's documentation for more details.

"}],"types":["relative","dictionary"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"outset","details":[{"kind":"html","content":"

How much to expand the block's size without affecting the layout. See\nthe box's documentation for more details.

"}],"types":["relative","dictionary"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"spacing","details":[{"kind":"html","content":"

The spacing around the block. When auto, inherits the paragraph\nspacing.

\n

For two adjacent blocks, the larger of the first block's above and the\nsecond block's below spacing wins. Moreover, block spacing takes\nprecedence over paragraph spacing.

\n

Note that this is only a shorthand to set above and below to the\nsame value. Since the values for above and below might differ, a\ncontext block only provides access to block.above and\nblock.below, not to block.spacing directly.

\n

This property can be used in combination with a show rule to adjust the\nspacing around arbitrary block-level elements.

"},{"kind":"example","content":{"body":"
#set align(center)\n#show math.equation: set block(above: 8pt, below: 16pt)\n\nThis sum of $x$ and $y$:\n$ x + y = z $\nA second paragraph.\n
\"Preview\"
","title":null}}],"types":["relative","fraction"],"strings":[],"default":"1.2em","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"above","details":[{"kind":"html","content":"

The spacing between this block and its predecessor.

"}],"types":["auto","relative","fraction"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"below","details":[{"kind":"html","content":"

The spacing between this block and its successor.

"}],"types":["auto","relative","fraction"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"clip","details":[{"kind":"html","content":"

Whether to clip the content inside the block.

\n

Clipping is useful when the block's content is larger than the block itself,\nas any content that exceeds the block's bounds will be hidden.

"},{"kind":"example","content":{"body":"
#block(\n  width: 50pt,\n  height: 50pt,\n  clip: true,\n  image("tiger.jpg", width: 100pt, height: 100pt)\n)\n
\"Preview\"
","title":null}}],"types":["bool"],"strings":[],"default":"false","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"sticky","details":[{"kind":"html","content":"

Whether this block must stick to the following one, with no break in\nbetween.

\n

This is, by default, set on heading blocks to prevent orphaned headings\nat the bottom of the page.

"},{"kind":"example","content":{"body":"
// Disable stickiness of headings.\n#show heading: set block(sticky: false)\n#lorem(20)\n\n= Chapter\n#lorem(10)\n
\"Preview\"Preview
","title":null}}],"types":["bool"],"strings":[],"default":"false","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"body","details":[{"kind":"html","content":"

The contents of the block.

"}],"types":["none","content"],"strings":[],"default":"none","positional":true,"named":false,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]}}}