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 button in the toolbar, which looks like this:
The Table Properties dialog box opens:
There are two tabs here: Table Properties and Advanced.
Table Properties tab
This tab is where you'll do most of your work configuring the table, as there are very few items in the Advanced tab that we recommend using. The options here are:
- The number of rows in your table. You may add more rows while in the editor, but this lets you quickly configure your table.
- The number of columns in your table.
- 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.
- 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.
- 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.
- You should typically leave this blank, as you should be providing appropriate explanatory text adjacant to your table.
The Advanced tab 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. 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.
- 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 the OK button to create it.
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:
- On browsers that support pasting via script (some, including Firefox, do not, for security purposes), selecting this option pastes the contents of the clipboard at the current point in the table.
- This submenu offers options related to the selected cell or cells. See Cell options.
- This submenu offers options related to the selected row or rows. See Row options.
- This submenu offers options related to the selected column or columns. See Column options.
- Delete Table
- Deletes the entire table.
- 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.
The Cell 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 available only if you have selected multiple cells; you can then use this option to combine them into a single cell. The Merge Right and Merge Down options merge the current cell with the one to the right, or below, respectively.
Cell Properties dialog box
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:
- 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.
- 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. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable are covered by CSS classes.
- Border Color
- Lets you specify a border color for the cel. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable are covered by CSS classes.
The Row submenu gives you options you may use to adjust and refine the rows in your table:
These options are all straightforward:
- Insert Row Before adds a new row before the current cursor position in the table
- 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)
The Column submenu lets you edit the columns in your table:
These options mirror those in the row options menu:
- Insert Column Before adds a new column to the left of the current cursor position in the table (or to the right in right-to-left languages)
- Insert Column After adds a new row to the right of the current location (or to the left in right-to-left languages)
- Delete Columns removes the column containing the insertion point, or all selected columns (or all columns in which you have selected cells)