Tables

Tables are a useful way to present information; this article covers how to create and maintain tables on MDN and when you should and should not use them.

On MDN, we use tables primarily when presenting lists of information with more than two pieces of information per data point. If you're creating a list of items with a name and a value, you should typically use a definition list instead of a table; that is, we prefer to avoid using two-column tables. This is primarily because tables can be difficult to display and to read on mobile devices, so we try to avoid them when possible.

Please see the MDN style guide for details on use of tables and their proper formatting; however, let's look at the actual technique by which you insert and edit tables.

Creating a table

To insert a new table, click the Table icon in the toolbar, which looks like this:

Having done this, you'll be presented with the Table Properties dialog:

There are two panels here: Table Properties and Advanced.

Table properties

This panel is where you'll do most of your work configuring the table, as there are few items in the Advanced panel we recommend using. The options here are:

Rows

The number of rows in your table. You may add more rows while in the editor, but this lets you quickly configure your table.

Columns

The number of columns in your table.

Headers

Lets you configure where your headers are, if any. By default, no header cells are added to your table; however, we generally prefer that tables have headers, so you should change this most of the time. The possible values are None, First row, First column, and Both.

Alignment

Lets you align the table along the left, right, or center of the article. Please do not use this option. Our style guide specifies that tables should always be left-aligned. There are very few exceptions to this rule (usually only when we're being naughty and using tables for layout, which we're working on getting out of the habit of doing as we build out our CSS).

Caption

You may choose to add a caption to your table; however, we do not usually do so on MDN, so you will probably leave this blank.

Summary

You should typically leave this blank, as you should be providing appropriate explanatory text adjacant to your table.

Advanced

The Advanced panel provides a few additional options, most of which we don't use on MDN and will likely remove in the future.

As you see here, there are only four options; they are:

Id

The <table> element's id. We generally do not use IDs on tables on MDN.

Language Direction

Lets you establish the writing direction used in the table. This should be used only when localizing content.

Style

This field lets you hand-enter custom CSS. Do not use this field! We will probably remove your table if you do. We are trying to eliminate all uses of custom styles outside what's provided by our stylesheets.

Stylesheet Classes

This lets you specify a stylesheet class to use for the table. This should nearly always be "standard-table", which is our standard table class.

Once you've finished configuring your table, click "OK" to create it.

Maintaining tables

Once a table has been created, working with it is very much like in any table editor, entering data into its cells. Pressing the tab key will advance you to the next cell in the table, wrapping to the next row if you're in the last cell in the row you're currently working on. If you're in the last cell of the last row when you press tab, a new row will be added to the end of the table, and the cursor will be placed in the first cell of the new row.

You may right-click on the table to get an assortment of options for adjusting the cells, rows, columns, and the table itself:

Paste

On browsers that support pasting via script (some, including Firefox, do not, for security purposes), this will paste your clipboard at the current point in the table.

Cell

This submenu offers options related to the selected cell or cells. See Cell options.

Row

This submenu offers options related to the selected row or rows. See Row options.

Column

This submenu offers options related to the selected column or columns. See Column options.

Delete Table

Deletes the entire table. This option is listed twice due to a glitch we've yet to track down. Both do the same thing.

Sort Table

Opens a dialog box providing options for sorting the contents of the table. See Sorting tables below.

Table Properties

Opens the same table properties dialog used to create a new table. This option is listed twice due to a bug we haven't resolved yet. Both work just fine.

Cell options

The cell options submenu offers options related to manipulating and editing cells in your table, and looks like this:

These options should be fairly self-explanatory, with the exception that "Merge Cells" is only available if you have selected multiple cells; you can then use this option to combine them into a single cell.

Cell properties

The Cell Properties option opens a dialog box that gives you control over the details of a cell:

The options you can configure here are:

Width

The width of the cell; you may change the units used for this value using the adjacent drop-down. Please don't use this. You shouldn't need to adjust widths of cells except in rare cases involving nesting images or example code within tables.

Height

The cell's height; this is always in pixels. Please don't use this. We prefer for cell sizes to be determined automatically, except in exceptionally rare cases.

Word Wrap

Specifies whether or not the cell's contents should be permitted to wrap. This should almost always be left at "Yes", the default.

Horizontal Alignment

Allows you to set the horizontal alignment for the cell's or cells' contents. This should almost always be left at the default.

Vertical Alignment

Lets you set the vertical alignment of the cell or cells. This should nearly always be left at the default, but may be adjusted if necessary.

Cell Type

Lets you specify whether the cell or cells contain data or header information. Making a row a header row gives it header styling that stands out from the data within the table.

Rows Span

Lets you specify how many rows the cell should take up within the table. Rarely needed, but useful for certain types of table.

Columns Span

Lets you indicate how many columns the cell should occupy within the table. You should rarely need to use this option.

Background Color

Lets you specify a background color for the cell; clicking "Choose" opens a color picker to make it easier to find a color you like. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable will soon be covered by CSS classes.

Border Color

Lets you specify a border color for the cell; clicking "Choose" opens a color picker to make it easier to find a color you like. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable will soon be covered by CSS classes.

Row options

The row options submenu gives you options you may use to adjust and refine the rows in your table:

These options are all straightforward; Insert Row Before lets you add a new row before the current cursor position in the table, while Insert Row After adds a new row below the current row. Delete Rows removes the row containing the insertion point, or all selected rows (or all rows on which you have selected cells).

Column options

The column options submenu lets you edit the columns in your table:

These options mirror those in the row options menu; Insert Column Before lets you add a new column to the left of the current cursor position in the table, while Insert Column After adds a new row to the right of the current location. Delete Columns removes the column containing the insertion point, or all selected columns (or all columns in which you have selected cells).