bokeh.layouts

Functions for arranging bokeh layout objects.

column

column(children: List[bokeh.models.layouts.LayoutDOM], *, sizing_mode: SizingModeType | None = 'None', **kwargs: Any) → bokeh.models.layouts.Column[source]
column(*children: bokeh.models.layouts.LayoutDOM, sizing_mode: SizingModeType | None = 'None', **kwargs: Any) → bokeh.models.layouts.Column

Create a column of Bokeh Layout objects. Forces all objects to have the same sizing_mode, which is required for complex layouts to work.

Parameters

  • children (list of LayoutDOM) – A list of instances for the column. Can be any of the following - Plot, Widget, Row, Column, ToolbarBox, Spacer.

  • sizing_mode ("fixed", "stretch_both", "scale_width", "scale_height", "scale_both") – How will the items in the layout resize to fill the available space. Default is "fixed". For more information on the different modes see sizing_mode description on LayoutDOM.

Returns

A column of LayoutDOM objects all with the same sizing_mode.

Return type

Column

Examples

>>> column(plot1, plot2)
>>> column(children=[widgets, plot], sizing_mode='stretch_both')

grid

grid(children: List[LayoutDOM | List[LayoutDOM | List[Any]]], *, sizing_mode: SizingModeType | None = None) → bokeh.models.layouts.GridBox[source]
grid(children: Row | Column, *, sizing_mode: SizingModeType | None = None) → bokeh.models.layouts.GridBox
grid(children: List[LayoutDOM | None], *, sizing_mode: SizingModeType | None = None, nrows: int) → bokeh.models.layouts.GridBox
grid(children: List[LayoutDOM | None], *, sizing_mode: SizingModeType | None = None, ncols: int) → bokeh.models.layouts.GridBox
grid(children: List[LayoutDOM | None], *, sizing_mode: SizingModeType | None = None, nrows: int, ncols: int) → bokeh.models.layouts.GridBox
grid(children: str, *, sizing_mode: SizingModeType | None = None) → bokeh.models.layouts.GridBox

Conveniently create a grid of layoutable objects.

Grids are created by using GridBox model. This gives the most control over the layout of a grid, but is also tedious and may result in unreadable code in practical applications. grid() function remedies this by reducing the level of control, but in turn providing a more convenient API.

Supported patterns:

  1. Nested lists of layoutable objects. Assumes the top-level list represents a column and alternates between rows and columns in subsequent nesting levels. One can use None for padding purpose.

    >>> grid([p1, [[p2, p3], p4]])
GridBox(children=[
    (p1, 0, 0, 1, 2),
    (p2, 1, 0, 1, 1),
    (p3, 2, 0, 1, 1),
    (p4, 1, 1, 2, 1),
])

  2. Nested Row and Column instances. Similar to the first pattern, just instead of using nested lists, it uses nested Row and Column models. This can be much more readable that the former. Note, however, that only models that don’t have sizing_mode set are used.

    >>> grid(column(p1, row(column(p2, p3), p4)))
GridBox(children=[
    (p1, 0, 0, 1, 2),
    (p2, 1, 0, 1, 1),
    (p3, 2, 0, 1, 1),
    (p4, 1, 1, 2, 1),
])

  3. Flat list of layoutable objects. This requires nrows and/or ncols to be set. The input list will be rearranged into a 2D array accordingly. One can use None for padding purpose.

    >>> grid([p1, p2, p3, p4], ncols=2)
GridBox(children=[
    (p1, 0, 0, 1, 1),
    (p2, 0, 1, 1, 1),
    (p3, 1, 0, 1, 1),
    (p4, 1, 1, 1, 1),
])

gridplot

gridplot(children: List[List[LayoutDOM | None]] | GridSpec, *, sizing_mode: SizingModeType | None = None, toolbar_location: LocationType | None = 'above', ncols: int | None = None, width: int | None = None, height: int | None = None, plot_width: int | None = None, plot_height: int | None = None, toolbar_options: Any = None, merge_tools: bool = True) → LayoutDOM[source]

Create a grid of plots rendered on separate canvases.

The gridplot function builds a single toolbar for all the plots in the grid. gridplot is designed to layout a set of plots. For general grid layout, use the layout() function.

Parameters

  • children (list of lists of Plot) – An array of plots to display in a grid, given as a list of lists of Plot objects. To leave a position in the grid empty, pass None for that position in the children list. OR list of Plot if called with ncols. OR an instance of GridSpec.

  • sizing_mode ("fixed", "stretch_both", "scale_width", "scale_height", "scale_both") – How will the items in the layout resize to fill the available space. Default is "fixed". For more information on the different modes see sizing_mode description on LayoutDOM.

  • toolbar_location (above, below, left, right) – Where the toolbar will be located, with respect to the grid. Default is above. If set to None, no toolbar will be attached to the grid.

  • ncols (int, optional) – Specify the number of columns you would like in your grid. You must only pass an un-nested list of plots (as opposed to a list of lists of plots) when using ncols.

  • width (int, optional) – The width you would like all your plots to be

  • height (int, optional) – The height you would like all your plots to be.

  • toolbar_options (dict, optional) – A dictionary of options that will be used to construct the grid’s toolbar (an instance of ToolbarBox). If none is supplied, ToolbarBox’s defaults will be used.

  • merge_tools (True, False) – Combine tools from all child plots into a single toolbar.

Returns

A row or column containing the grid toolbar and the grid

of plots (depending on whether the toolbar is left/right or above/below. The grid is always a Column of Rows of plots.

Return type

Row or Column

Examples

>>> gridplot([[plot_1, plot_2], [plot_3, plot_4]])
>>> gridplot([plot_1, plot_2, plot_3, plot_4], ncols=2, width=200, height=100)
>>> gridplot(
        children=[[plot_1, plot_2], [None, plot_3]],
        toolbar_location='right'
        sizing_mode='fixed',
        toolbar_options=dict(logo='gray')
    )

GridSpec

class GridSpec(nrows: int, ncols: int)[source]

Simplifies grid layout specification.

layout

layout(*args: LayoutDOM, children: List[LayoutDOM] | None = None, sizing_mode: SizingModeType | None = None, **kwargs: Any) → Column[source]

Create a grid-based arrangement of Bokeh Layout objects.

Parameters

  • children (list of lists of LayoutDOM) – A list of lists of instances for a grid layout. Can be any of the following - Plot, Widget, Row, Column, ToolbarBox, Spacer.

  • sizing_mode ("fixed", "stretch_both", "scale_width", "scale_height", "scale_both") – How will the items in the layout resize to fill the available space. Default is "fixed". For more information on the different modes see sizing_mode description on LayoutDOM.

Returns

A column of Row layouts of the children, all with the same sizing_mode.

Return type

Column

Examples

>>> layout([[plot_1, plot_2], [plot_3, plot_4]])
>>> layout(
        children=[
            [widget_1, plot_1],
            [slider],
            [widget_2, plot_2, plot_3]
        ],
        sizing_mode='fixed',
    )

row

row(children: List[bokeh.models.layouts.LayoutDOM], *, sizing_mode: SizingModeType | None = 'None', **kwargs: Any) → bokeh.models.layouts.Row[source]
row(*children: bokeh.models.layouts.LayoutDOM, sizing_mode: SizingModeType | None = 'None', **kwargs: Any) → bokeh.models.layouts.Row

Create a row of Bokeh Layout objects. Forces all objects to have the same sizing_mode, which is required for complex layouts to work.

Parameters

  • children (list of LayoutDOM) – A list of instances for the row. Can be any of the following - Plot, Widget, Row, Column, ToolbarBox, Spacer.

  • sizing_mode ("fixed", "stretch_both", "scale_width", "scale_height", "scale_both") – How will the items in the layout resize to fill the available space. Default is "fixed". For more information on the different modes see sizing_mode description on LayoutDOM.

Returns

A row of LayoutDOM objects all with the same sizing_mode.

Return type

Row

Examples

>>> row(plot1, plot2)
>>> row(children=[widgets, plot], sizing_mode='stretch_both')

Spacer

class Spacer(*args, **kwargs)[source]

A container for space used to fill an empty spot in a row or column.

widgetbox

Warning

widgetbox is deprecated. Use column instead.

widgetbox(*args: Widget, children: List[Widget] | None = None, sizing_mode: SizingModeType | None = None, **kwargs: Any) → WidgetBox[source]

Create a column of bokeh widgets with predefined styling.

Parameters

  • children (list of Widget) – A list of widgets.

  • sizing_mode ("fixed", "stretch_both", "scale_width", "scale_height", "scale_both") – How will the items in the layout resize to fill the available space. Default is "fixed". For more information on the different modes see sizing_mode description on LayoutDOM.

Returns

A column layout of widget instances all with the same sizing_mode.

Return type

WidgetBox

Examples

>>> widgetbox([button, select])
>>> widgetbox(children=[slider], sizing_mode='scale_width')
bokeh.io bokeh.model