Grids, Rows, and Columns in the Wolfram System

The Basic Constructs

The Wolfram Language provides a broad range of powerful constructs for laying out content on a screen or page. They are designed to be immediately useful for the beginner, yet also allow fine control over almost every aspect of their appearance.

These constructs can be placed into three families: constructs that appear within notebooks as typesetting structures, functions that generate graphics whose contents are arranged on a grid, and constructs that can appear inside grids to adjust details of formatting.

Grid, Column, and Row form the first family, referred to in this tutorial as the Grid family. The Grid family's defining characteristic is that it is a tightly integrated part of the Wolfram Language's typesetting system. This means that any expression whatsoever can appear as content, and that the construct itself can respond to changes such as window width or even the size of its elements. Like other typesetting constructs, the Grid family's members are inert constructs and do not evaluate to some other form.

Click for copyable input

A parallel set of constructsthe Graphics Grid familysupports features particularly useful when dealing with graphics. These constructs are GraphicsGrid, GraphicsColumn, and GraphicsRow. Though graphics can be used in the Grid family, the Graphics Grid family supports sizing and editing behavior more tailored to graphics. The Graphics Grid family has functions that take arguments and evaluate them into new graphics expressions, which means it is difficult to make the generated grid respond to changes in its environment, but easy to interactively add arbitrary annotation and additional graphics.

Click for copyable input

The final familythe Embedded Constructs familyconsists of constructs that are embedded within the grids themselves, and alter the grid's appearance from within. Item can be wrapped around elements in a grid in order to style the region in which they appear. SpanFromLeft, SpanFromAbove, and SpanFromBoth are used to create regions that span across multiple rows or columns.

Click for copyable input

Some very basic examples of all of these constructs follow.

Grid Family

Grid[{{expr11,expr12,},{expr21,expr22,},}]
an object that formats with the arranged in a two-dimensional grid
Column[{expr1,expr2,}]an object that formats with the arranged in a column, with above , etc.
Row[{expr1,expr2,}]an object that formats with the arranged in a row, potentially extending over several lines

The Grid family of 2D formatting constructs.

A grid of elements.
In[684]:=
Click for copyable input
Out[684]=
A column of elements.
In[686]:=
Click for copyable input
Out[686]=
A row of elements.
In[685]:=
Click for copyable input
Out[685]=

Graphics Grid Family

GraphicsGrid[{{g11,g12,},}]generates a graphic in which the are laid out in a two-dimensional grid
GraphicsColumn[{g1,g2,}]generates a graphic in which the are laid out in a column, with above , etc.
GraphicsRow[{g1,g2,}]generates a graphic in which the are laid out in a row

The Graphics Grid family of 2D graphics layout functions.

Display elements in a graphics grid.
In[678]:=
Click for copyable input
Out[678]=
Display elements in a graphics column.
In[689]:=
Click for copyable input
Out[689]=
Display elements in a graphics row.
In[691]:=
Click for copyable input
Out[691]=

Embedded Constructs Family

Item[expr,options]displays with expr as the content, and with the specified options applied to the region containing expr
SpanFromLeftindicates that the position is occupied by the contents on the left
SpanFromAboveindicates that the position is occupied by the contents above
SpanFromBothindicates that the position is occupied from both above and left

Constructs with special meaning when they are embedded as elements within the Grid and Graphics Grid families.

Embed styling information around the element .
In[708]:=
Click for copyable input
Out[708]=
Span across the first two columns.
In[709]:=
Click for copyable input
Out[709]=
Span across the first two rows.
In[710]:=
Click for copyable input
Out[710]=
Span across the first two columns and rows.
In[711]:=
Click for copyable input
Out[711]=

Classes of Functionality

Grid and related constructs allow considerable appearance customization, often with very little syntax. The tables below indicate the kind of functionality that is supported; it is explained in detail in later sections.

    • Frames and dividers can be placed in any position to partition regions of the grid.
    • The grid and its contents can be aligned and positioned in a number of ways.
    • Backgrounds and styles can be imposed on any region.
    • The structure can be elaborated using spanning elements, or elements that are themselves grids.
    • The sizes and spacings in the grid can be adjusted.

    In addition to these styling features, various forms of interactive editing and dynamic behavior are possible.

Options Syntax

A variety of options exist for adjusting the details of a grid's appearance. This section describes the common syntax shared by many of these options. This syntax provides a way to assign option values not only for the entire grid, but also for individual rows, columns, and even items.

The overall syntax for many options, such as Background, is based on forms like Background->{specx,specy}, where is itself a modular syntax that contains values for different columns, while contains values for the different rows.

specapply spec to all items
{specx}apply at successive horizontal positions
{specx,specy}apply at successive horizontal and vertical positions
{specx,specy,rules}give rules for the items based on their position in the array

General options syntax.

and may take two possible forms, as described below. The first form is just the rules for the desired value at a set of indices. The second form is based on giving a sequence of values in a list.

A set of rules specifying the index of a column and its desired background.
In[8]:=
Click for copyable input
Out[8]=
An equivalent list of background values to use for successive columns.
In[9]:=
Click for copyable input
Out[9]=

These two methods have different strengths, as described in "Using Rules" and "Using Lists".

Using Rules

Rules provide a direct and readable method to give a specific row or column a specific value.

Set the background for specific sets of columns.
In[16]:=
Click for copyable input
Out[16]=
Set the background for specific sets of rows.
In[26]:=
Click for copyable input
Out[26]=

When there are a large number of rows or columns, rules are a convenient way to set the properties of just a few of them.

Apply the option at a small number of the possible positions.
In[25]:=
Click for copyable input
Out[25]=

Rules can also be used to give values to specific grid elements or subregions. Note however that while conceptually similar, this following syntax is separate from the discussion of and .

Set the background of the element at position .
In[27]:=
Click for copyable input
Out[27]=
Set the background of the region from element to .
In[28]:=
Click for copyable input
Out[28]=

Rules are an efficient way to specify the exceptions to the value that otherwise exists. However, they are less efficient when the intention is to manually specify a value for each piece of the grid.

Manually specify an alternating pattern using rules.
In[31]:=
Click for copyable input
Out[31]=

To achieve repetitive patterns, it is instead recommended to use the list syntax described in the next section.

Using Lists

Giving sequential values in a list is a compact and convenient way to specify large numbers of option values for adjacent rows or columns.

List the values to be used for successive columns.
In[52]:=
Click for copyable input
Out[52]=

Additionally, sublists can be used to denote cyclic use of values.

Specify that the list should be used cyclically.
In[53]:=
Click for copyable input
Out[53]=

These cyclic sublists can be padded at the beginning or end.

Give an initial set of values before the cyclic portion.
In[58]:=
Click for copyable input
Out[58]=
Give a final set of values.
In[57]:=
Click for copyable input
Out[57]=
Use defaults in the middle.
In[7]:=
Click for copyable input
Out[7]=

Because positions in the list correspond to positions in the grid, specifying a single value in the middle requires giving all previous values. To achieve this more directly, use rules as described in the section "Using Rules".

Make the fifth column red using the list syntax.
In[61]:=
Click for copyable input
Out[61]=
Use a rule to directly assign the background.
In[62]:=
Click for copyable input
Out[62]=

Using Both

It is possible to have the best of both worlds, using the list syntax for specifying repetitive portions of the grid while also using the rule syntax to specify exceptions.

Columns alternate between blue and green, except the first and last which are red.
In[746]:=
Click for copyable input
Out[746]=
Use blue for all columns, except the first and fifth.
In[89]:=
Click for copyable input
Out[89]=
{s1,s2,,sn}use through ; then use defaults
{{c}}use c in all cases
{{c1,c2}}alternate between and
{{c1,c2,}}cycle through all
{s,{c}}use s, then repeatedly use c
{s1,{c},sn}use , then repeatedly use c, but use at the end
{s1,s2,,{c1,c2,},sm,,sn} use the first sequence of at the beginning, then cyclically use the , then use the last sequence of at the end
{s1,s2,,{},sm,,sn}use the first sequence of at the beginning and the last sequence at the end
{i1->v1,i2->v2,}specify what to use at positions
{spec,rules}use rules to override specifications in spec

Summary of syntax for and .

Columns, Rows, Gutters, and Items

As introduced in the previous section, the Wolfram Language provides a flexible syntax for changing an option's value in different regions of a grid. This section provides context for that language and elaborates on the finer distinctions.

Vocabulary for grids.

columnvertical sequence of items
rowhorizontal sequence of items
itemthe region containing a grid element
gutterthe border between consecutive rows or columns

Different slices of a 2D grid.

Grid and GraphicsGrid follow the same conventions for describing the different possible slices of the grid. Column, GraphicsColumn, and GraphicsRow follow the same general conventions, except that they only deal in one of the two possible dimensions. Finally, Row does not participate in this system at all.

The World of Options

The following table identifies the slices each listed option can address. No option is valid for all constructs; refer to the key below to see which option can occur for a given construct.

Out[54]=
Out[53]=

Note that Row does not take any options.

Columns, Then Rows

To remember the syntax for options, the most important step is knowing that specific values for the columns are specified first, and values for rows are specified second.

opt->valuse val for all items
opt->{colspec,rowspec}use colspec for columns, rowspec for rows
opt->{colspec}use colspec for columns, defaults for rows

Option structure for Grid and GraphicsGrid.

In the Wolfram Language, options with a horizontal setting h and a vertical setting v are specified as . ImageSize and PlotRange are two common options that help establish this convention.

In a grid, these horizontal and vertical settings correspond to values for the columns and rows, respectively. This is because columns are stacked horizontally, and so their propertiessuch as width and locationcorrespond to the horizontal dimension. Rows are stacked vertically, and their properties correspond to the vertical dimension.

A graphic that is twice as long as it is tall.
In[37]:=
Click for copyable input
Out[37]=
In the following grid each item is 2 "ems" wide and 1 "ex" tall.
In[1]:=
Click for copyable input
Out[1]=
Instead of a single width for all columns, a separate setting is given for each column.
In[29]:=
Click for copyable input
Out[29]=
In[2]:=
Click for copyable input
Out[2]=
Similarly, a different background color can be given at successive horizontal positions.
In[6]:=
Click for copyable input
Out[6]=

Gutters

Many Grid options deal with properties that can ultimately be associated with a column, row, or item in the grid.

However there are also options that deal with gutters between rows and columns.

Dividerswhere to draw divider lines in the grid
Spacingshorizontal and vertical spacings

Options for the gutters between rows and columns.

A line that is not associated with any single row or column.
In[85]:=
Click for copyable input
Out[85]=
Compare this with a frame.
In[86]:=
Click for copyable input
Out[86]=

The syntax for Dividers and Spacings is exactly the same as for the other options. For a grid with n items in a particular direction, Dividers and Spacings can specify settings for the gaps between elements, starting before the first element and ending after the last element.

Items

The most granular level of description is the item. Each item in a grid can have its own value for options such as Background, Alignment, and Frame.

Item can be used to explicitly indicate the desired settings.
In[100]:=
Click for copyable input
Out[100]=
Alternatively, use the item's index to assign it a value at the overall grid level.
In[101]:=
Click for copyable input
Out[101]=
A programmatically generated grid.
In[103]:=
Click for copyable input
Out[103]=
Give settings to an entire region of the grid.
In[105]:=
Click for copyable input
Out[105]=
In[109]:=
Click for copyable input
Out[109]=

Dividers and Frames

The Wolfram Language provides an extensive system for describing what dividers and frames should be drawn in a grid.

Dividersdraw dividers between columns or rows
Frameput a frame around regions of the grid
FrameStyleuse an overall style for the lines

Options for drawing dividers and frames.

Use Frame to put lines on all four sides of a region or set of regions.
In[131]:=
Click for copyable input
Out[131]=
Highlight specific columns or rows.
In[141]:=
Click for copyable input
Out[141]=

Frame always draws a line on all four faces of the enclosed region. Dividers allows a finer level of control.

In[140]:=
Click for copyable input
Out[140]=

One result is that when using dividers, the resulting lines run in only a single direction.

In[147]:=
Click for copyable input
Out[147]=
In[146]:=
Click for copyable input
Out[146]=
This short form draws the center dividers.
In[150]:=
Click for copyable input
Out[150]=

Styling Dividers and Frames

FrameStyle sets the base style used for both Frame and Dividers.
In[94]:=
Click for copyable input
Out[94]=
In[95]:=
Click for copyable input
Out[95]=
Frame and Dividers allow styles as values.
In[50]:=
Click for copyable input
Out[50]=
In[48]:=
Click for copyable input
Out[48]=

In general, any line and color directive may be used, including Hue, Thickness, Dashing, Dotted, and others. Multiple directives may be combined with Directive.

Precedence

When conflicting styles are given, Dividers has precedence over Frame, and they have precedence over FrameStyle. Styles from Item take precedence over all others.

Dividers and frames are added together.
In[177]:=
Click for copyable input
Out[177]=
Styles from different sources are combined together.
In[185]:=
Click for copyable input
Out[185]=

Alignment and Positioning

Aesthetic grids often require use of alignment. The Wolfram Language has considerable support for different kinds of alignment in grids.

The Alignment option can be passed to the overall grid.

Align contents to the right.
In[53]:=
Click for copyable input
Out[53]=

It is possible to give different horizontal alignments to different columns, and different vertical alignments to different rows.

Align the first column to the right, and the second column to the left.
In[61]:=
Click for copyable input
Out[61]=

It is also possible to give different alignments to the individual items in the grid.

Set the element at position to the left, and the element at position to the right.
In[62]:=
Click for copyable input
Out[62]=
Alignment can also be set with Item. The specification for Item will take precedence.
In[63]:=
Click for copyable input
Out[63]=

It is possible to align on a decimal point, or any character.

Align on ".".
In[65]:=
Click for copyable input
Out[65]=

Positioning a grid within its enclosing environment can be achieved with BaselinePosition.

Default position.
In[67]:=
Click for copyable input
Out[67]=
Align the bottom of the grid to the baseline of the enclosing expression.
In[73]:=
Click for copyable input
Out[73]=
Align the grid so that the baseline of the element is at the overall baseline.
In[74]:=
Click for copyable input
Out[74]=

Background and Style

Common Cases

When working with a collection of elements, Grid provides a way to set them against a uniform background.

Though an element can have its own background, awkward gaps result when you put elements together.

In[193]:=
Click for copyable input
Out[193]=

Grid and related functions place a background across the entire group of items in which the elements are contained.

In[194]:=
Click for copyable input
Out[194]=

With more sophisticated syntax, a variety of patterns is easy to achieve.

Alternate the backgrounds.
In[195]:=
Click for copyable input
Out[195]=
In[196]:=
Click for copyable input
Out[196]=
Highlight a row and column that intersect.
In[197]:=
Click for copyable input
Out[197]=
Embed the background with a particular item inside the grid.
In[107]:=
Click for copyable input
Out[107]=

Precedence of Overlapping Background Settings

Backgrounds given in the list syntax blend together upon intersection.
In[198]:=
Click for copyable input
Out[198]=
Backgrounds specifically asserted using indices take precedence.
In[199]:=
Click for copyable input
Out[199]=
Indexed columns take precedence over indexed rows.
In[200]:=
Click for copyable input
Out[200]=
Backgrounds specified with Item have the highest precedence.
In[201]:=
Click for copyable input
Out[201]=

Spanning and Nesting

Sophisticated partitioning of 2D space can be achieved by nested grid constructs and/or by using spanning elements.

As their name suggests, spanning elements allow an item to span multiple columns, rows, or both.

Span across the first two columns.
In[709]:=
Click for copyable input
Out[709]=
Span across the first two rows.
In[710]:=
Click for copyable input
Out[710]=
Span across the first two columns and rows.
In[711]:=
Click for copyable input
Out[711]=

It is important to note that the spanning region must be rectangular; items that fail to fall within the rectangle will not be spanned, and will instead display the spanning character.

Spanning is only done in rectangular chunks.
In[75]:=
Click for copyable input
Out[75]=
While many layouts can be achieved using spanning elements, it is sometimes faster or more convenient to simply nest grid constructs.
In[81]:=
Click for copyable input
Out[81]=
In[84]:=
Click for copyable input
Out[84]=

Particularly with complex grids, it is often clearer to use Row and Column to create the specifically desired structures than to try to design a complicated system of spanning.

Sizing and Spacing

Sizing in Grid

Grid will typically not modify the size of its elements. Also, rows and columns are by default made as narrow as possible while accommodating the contents.

In[275]:=
Click for copyable input
Out[275]=

Notice in the above example that the second row is much taller than the first, the second column thinner than the first, and the sizes of the elements were not modified in any way.

If elements in the grid are interactively or dynamically changed, the size of the entire grid will automatically adjust as appropriate.

A useful exception is that Button will by default expand to fill the available space.

In[277]:=
Click for copyable input
Out[277]=

ItemSize can be used to override the default behavior.

Make all items the same size.
In[278]:=
Click for copyable input
Out[278]=
Specify widths and heights for individual columns and rows.
In[256]:=
Click for copyable input
Out[256]=

The units used for ItemSize are the typesetting units known as "exs" and "ems."

It is also possible to specify widths as a fraction of the enclosing area by using Scaled.

Make the first two columns each .3 of the page width.
In[274]:=
Click for copyable input
Out[274]=

Line Wrapping in Grid

Textual items will line wrap if the columns are too narrow. Notice that this forces the rows to be taller than the minimum specified.

In[266]:=
Click for copyable input
Out[266]=
With ItemSize->Automatic, textual items are wrapped at the page width.
In[271]:=
Click for copyable input
Out[271]=
With ItemSize->Full, line breaking is prevented.
In[273]:=
Click for copyable input
Out[273]=

Sizing in GraphicsGrid

GraphicsGrid will by default return a grid whose items are all the same size.

In[286]:=
Click for copyable input
In[289]:=
Click for copyable input
Out[289]=

It will automatically choose an aspect ratio that is appropriate for the overall collection of elements.

Compare this with the equivalent Grid example, which does not impose either an overall size or an aspect ratio.

In[290]:=
Click for copyable input
Out[290]=

GraphicsGrid does not support an ItemSize option, but it does support ImageSize.

In[294]:=
Click for copyable input
Out[294]=