Colored tables (colortbl)

The colortbl package does not tint the background of a LaTeX table’s cells. It lays colored panels behind them — that is the wording of its author, David Carlisle, in his own documentation. Almost every puzzling thing about table color follows from that one sentence: why a \cline you asked for is nowhere to be seen, and why a white band survives between your shading and a booktabs rule. This page starts from the single line \usepackage[table]{xcolor} and works through \rowcolor (rows), \columncolor (columns), \cellcolor (cells), \rowcolors for zebra stripes and \arrayrulecolor for rules — ending with the case, argued by booktabs, that you should perhaps not be using color at all.

Which package do you need to color a table

One line, \usepackage[table]{xcolor}, is all you need. There is no reason to load colortbl explicitly: the table option of xcolor drags it in for you. You can go the other way and write just \usepackage{colortbl}, but then you are short of color names. colortbl internally requires array and color, and color defines almost no names of its own, so the moment you write \rowcolors{2}{gray}{white} the run stops with ! LaTeX Error: Undefined color 'gray'. Supplying names and mixing is exactly what xcolor is for, which is why in practice everyone settles on the one line with [table].

% one line brings in both xcolor and colortbl
\usepackage[table]{xcolor}

Only beamer spells it differently: pass it as a class option, \documentclass[xcolor=table]{beamer}. For the colors themselves any xcolor expression works, so besides plain names like gray and red you can write gray!20 (20% intensity) or red!30!yellow (30% red mixed into yellow). A saturated color behind text makes the text unreadable, so the practical range for table shading is a diluted name!15 to name!25.

Option clash for package xcolor — and why it mostly stopped happening

! LaTeX Error: Option clash for package xcolor. used to be the mine most often stepped on when coloring tables. The cause was simple: tikz, pgfplots or beamer had already loaded xcolor with no options, so your later \usepackage[table]{xcolor} counted as reloading the same package with different options. xcolor 3.00, released 11 November 2023, changed that. From that version table is not a load-time option at all but a preamble key declared through LaTeX’s newer key/value handler, so it can be applied to an xcolor that is already loaded. On TeX Live 2024, loading tikz first and then writing \usepackage[table]{xcolor} raises no error at all — while the same experiment with geometry still stops at Option clash for package geometry.

So the advice still circulating on the web — “move [table] up to the class options” — is now a workaround for older installations. You will still meet those, though, so it is worth knowing the order to try. First move it to the class options: \documentclass[table]{article} gets your request in ahead of everyone else. If that fails, load \usepackage{colortbl} directly — what clashes is an option of xcolor, not colortbl itself. Note also that the new xcolor 3.00 behaviour only applies with LaTeX 2022-06-01 or newer; against an older format a frozen version is used automatically. Conversely, if the new behaviour disturbs an existing document, \usepackage{xcolor}[=v2] explicitly calls the old version back.

The difference between \rowcolor, \columncolor and \cellcolor

The three differ not only in what they shade but in where each one is written. \rowcolor{color} goes at the start of the row — before the content of that row’s first cell, that is, immediately after the preceding \\. \columncolor{color} goes not in the body of the table but inside the column specification, in the form >{\columncolor{gray!20}}. The >{…} hook comes from the array package, which injects material just before every cell of that column, and colortbl simply rides on it. Only \cellcolor{color} is unconstrained: anywhere inside the target cell will do. The asymmetry is awkward to memorise, but the reason for it is plain — a row can only be caught at the moment it begins, and a column can only be declared before the table starts.

All three share the same argument shape: \columncolor[model]{color}[left overhang][right overhang], with an optional color model before the color and optional left and right overhangs after it. The overhang says how far the colored panel spreads past the column on each side. Omit the right one and it copies the left; omit both and you get \tabcolsep in tabular, or \arraycolsep in array. Set both to 0pt and the panel is cut off exactly at the width of the column’s content — which is usually what produces a white seam between cells, so when you want adjacent colors to join up, the fix is to increase the overhang rather than reduce it.

\begin{tabular}{>{\columncolor{gray!20}}l c r}
  \rowcolor{blue!30}
  Item & Qty & Price \\
  Apple  & 3 & 380 \\
  Orange & \cellcolor{yellow!40}5 & 120 \\
\end{tabular}

This set of three was not designed in one go; it accumulated over two decades. The first draft of colortbl is dated 20 September 1996 and contained only \columncolor. \rowcolor arrived a fortnight later, on 5 October 1996, and the changelog records that it was added to make S. Rahtz happy — Sebastian Rahtz, one of the great figures of the TeX world. \cellcolor did not appear until five years after that, on 13 February 2001, contributed by Donald Arseneau. Until then, shading one cell meant writing \multicolumn{1}{>{\columncolor{…}}c}{…}, and Carlisle lists three objections to that: the cell’s content can prevent the coloring from triggering; the column alignment has to be copied by hand, which is error-prone especially for p{} columns; and third, that \multicolumn{1} is simply silly. To color one cell, reach for \cellcolor.

Which color wins when they overlap: cell over row over column

\cellcolor overrides \rowcolor, and \rowcolor overrides \columncolor — cell over row over column. The narrower the scope, the stronger the claim, which is exactly what intuition expects, so there is nothing to unlearn. Because of that order you can stack three layers without worrying about conflicts: a pale gray down a whole column, blue on the header row alone, and yellow on the single cell you want noticed. It helps to read the design as treating the broad declaration as a default and the narrow one as an exception to it.

Automatic zebra striping with \rowcolors

To alternate colors down a table, write \rowcolors{start}{odd-row color}{even-row color} once before the table and you are done. The trailing s matters: \rowcolor without it is the separate command that shades one row. The first argument is the row at which coloring begins, so pass 2 to let a header row through untouched. Either color argument may be left empty, and empty means “no color”. One point here contradicts most of the older articles you will find by searching: \rowcolors is no longer an xcolor command. The code was moved out of xcolor and into colortbl in version 1.0f, dated 20 June 2022, and the xcolor 3.00 changelog records the handover. Nothing changes in how you write it, but it is useful to know that today \usepackage{colortbl} alone already defines \rowcolors.

% start striping at row 2, so the header stays plain
\rowcolors{2}{gray!15}{white}
\begin{tabular}{l r r}
  Item & Qty & Price \\
  Apple  & 3 & 380 \\
  Orange & 5 & 120 \\
  Grape  & 2 & 600 \\
  Peach  & 4 & 450 \\
\end{tabular}

Striping is not all-or-nothing. First, \rowcolors takes a leading optional argument: \rowcolors[\hline]{2}{…}{…} runs a command such as \hline before each row. Second, an explicit \rowcolor or \multicolumn outranks the automatic striping, so recoloring one row in the middle of a striped run is straightforward. And for switching the stripes off temporarily there are \hiderowcolors and \showrowcolors, which can be placed inside the table to suppress and resume the pattern from that point on. A requirement like “everything striped except the totals row” is settled with these.

Coloring the rules with \arrayrulecolor and \doublerulesepcolor

The color of \hline, \cline and the vertical | is changed with \arrayrulecolor{color}. It takes the same arguments as \color and is a global declaration, so it may sit outside the table, at the start of a row, or in a >{} in the column spec. There is one trap. Given mid-table, it reaches only the rules specified after that point; vertical rules already declared in the column spec keep their original color. Being global, it also survives the end of the table, so unless you want every later table swept up in it, declare \arrayrulecolor{black} again to restore the default.

The gap between the double rules produced by || or \hline\hline stays white by default. To fill it, use \doublerulesepcolor{color} together with \doublerulesep, the length that sets the gap’s width. Be aware, though, that once this command is in play, longtable can no longer discard the space between \hline\hline at a page break. TeX does have machinery for discarding glue, but a colored “gap” is really a third rule, and rules are far harder to discard than glue. If a long table is going to break across pages, this is worth knowing in advance.

\setlength\arrayrulewidth{1pt}\arrayrulecolor{blue}
\setlength\doublerulesep{2pt}\doublerulesepcolor{yellow}
\begin{tabular}{||l|c||}
  \hline\hline
  one & two \\
  three & four \\
  \hline\hline
\end{tabular}
\arrayrulecolor{black} % global: reset, or later tables inherit it

To color just one vertical rule, you can skip the dedicated commands altogether and drop !{\color{green}\vline} into the column spec in place of |. A small but practical point: \arrayrulewidth is the length that sets rule thickness, and a rule left at the default hairline looks very weak once it is colored. A thickness that was ample in black can vanish off the page the moment it turns a light color — so as a rule of thumb, thicken a rule slightly when you color it.

Why \cline disappears under a colored row

Draw a \cline in a table that also uses \rowcolor and the rule becomes completely invisible. This is not a bug but a consequence of the mechanism from the opening paragraph. colortbl lays color as panels behind the cells, while \cline is drawn even further back than those panels, so the color covers it. In a comment in the source, Carlisle concedes that \cline does not really work in a colored table, and settles for at least giving the right color to the parts that remain visible. The workaround is clear: instead of \cline, load the hhline package and write something like \hhline{-~}, where - means draw a rule in this column and ~ means skip it. That rule is drawn on top of the panel and shows up properly.

% \cline{1-1} would vanish behind the panel; \hhline draws on top
\usepackage{hhline}
...
\begin{tabular}{ll}
  \rowcolor{blue!40} one & two \\
  \hhline{-~}
  \rowcolor{blue!40} three & four \\
\end{tabular}

The white gap between booktabs rules and your row color

colortbl and booktabs coexist without trouble, but a white band survives between \toprule / \midrule / \bottomrule and your background color. The cause is the space booktabs inserts above and below its rules — \aboverulesep defaults to .4ex and \belowrulesep to .65ex. That space lies outside the row’s box, so the panel from \rowcolor never reaches it. The standard fix when you want the fill to touch the rule is to set both to 0pt and move the lost height into \extrarowheight instead: the rows keep their height and only the color changes, now meeting the rules.

% let the row color reach the booktabs rules
\setlength\aboverulesep{0pt}
\setlength\belowrulesep{0pt}
\setlength\extrarowheight{.75ex}

The other classic symptom is large type or tall content touching the \hline or the top edge of the color panel just above it. Since colortbl already has to box and measure every entry in order to work out how wide the rules should be, the length \minrowclearance was added while it was at it. Setting \setlength\minrowclearance{2pt} inserts a little space above tall rows only. Carlisle himself notes, though, that it is better to first increase \extrarowheight or \arraystretch, which solve the problem while keeping the line spacing even — because once the height of a capital plus this value exceeds the normal row height, the leading becomes visibly uneven.

A closing question: should there be color here at all? Simon Fear, who wrote booktabs, was unambiguous. A good table is made readable by space and a few horizontal rules; keep two guidelines — never use vertical rules, never use double rules — and you will not go far wrong. He distinguishes the “formal table”, a set of values in labelled columns, from the “tableau”, which will likely be strewn with icons and use color too, and argues that the layout of the former was established over centuries of experience and should be altered only in extraordinary circumstances. Incidentally, the version number of booktabs is 1.61803398 — the author’s joke that it converges on φ, the golden ratio. Before shading a table, it is worth asking once whether row height and a couple of rules would have solved it.