class HexaPDF::Layout::ListBox


A ListBox arranges its children as unordered or ordered list items.

The indentation of the contents from the left (content_indentation) as well as the marker type of the items (marker_type) can be specified. Additionally, it is possible to define the start number for ordered lists (start_number) and the amount of spacing between items (item_spacing).

If the list box has padding and/or borders specified, they are handled like with any other box. This means they are around all items and their contents and are not used separately for each item.

The following style properties are used (additionally to those used by the parent class):


If this is set to :flow, the frames created for the list items will take the shape of the frame into account. This also means that the available_width and available_height arguments are ignored.



Stores the information when fitting an item of the list box.



The child boxes of this ListBox. They need to be finalized before fit is called.


The indentation of the list content in PDF points. The item marker will be inside this indentation.

The default value is two times the font size.

Example: {|list| list.lorem_ipsum_box(sentences: 1) }, content_indentation: 50) do |list|
  list.lorem_ipsum_box(sentences: 1)


The spacing between two consecutive list items.

The default value is zero.

Example:, item_spacing: 10) do |list|
  3.times { list.lorem_ipsum_box(sentences: 1) }


The type of list item marker to be rendered before the list item contents.

The following values are supported (and :disc is the default):


Draws a filled disc for the items of the unordered list., marker_type: :disc) do |list|
  list.lorem_ipsum_box(sentences: 1)


Draws an unfilled circle for the items of the unordered list., marker_type: :circle) do |list|
  list.lorem_ipsum_box(sentences: 1)


Draws a filled square for the items of the unordered list., marker_type: :square) do |list|
  list.lorem_ipsum_box(sentences: 1)


Draws the numbers in decimal form, starting from start_number) for the items of the ordered list., marker_type: :decimal) do |list|
  5.times { list.lorem_ipsum_box(sentences: 1) }

custom marker

Additionally, it is possible to specify an object as value that responds to call(document, box, index) where document is the HexaPDF::Document, box is the list box, and index is the current item index, starting at 0. The return value needs to be a Box object which is then fit into the content indentation area and drawn.

image = lambda do |document, box, index|
  document.layout.image_box(machu_picchu, height:
end, marker_type: image) do |list|
  2.times { list.lorem_ipsum_box(sentences: 1) }


The start number when using a marker_type that represents an ordered list.

The default value for this is 1.

Example:, marker_type: :decimal, start_number: 3) do |list|
  2.times { list.lorem_ipsum_box(sentences: 1) }

Public Class Methods

new(children: [], marker_type: :disc, content_indentation: nil, start_number: 1, item_spacing: 0, **kwargs)

Creates a new ListBox object for the given child boxes in children.

Calls superclass method HexaPDF::Layout::Box::new

Public Instance Methods


Returns true if no box was fitted into the list box.

Calls superclass method HexaPDF::Layout::Box#empty?
fit(available_width, available_height, frame)

Fits the list box into the current region of the frame.


Returns true as the ‘position’ style property value :flow is supported.