Custom labels

Most people remember the four labels — the markers — that LaTeX's itemize produces at successive levels as “•, -, , ·”. Open article.cls, though, and the last three are all something other than you would guess. Level 2 is not two hyphens but a bold en dash (\labelitemfont \bfseries \textendash); level 3 is not an ordinary asterisk but a vertically centred* one, \textasteriskcentered; level 4 is \textperiodcentered. Customising labels begins with knowing what these macros actually contain. This page works through the four itemize markers, the division of labour between \theenumi and \labelenumi in enumerate, the counter-representation commands from \arabic to \fnsymbol and where each one gives out, and the real limit on nesting — that is, when you actually see ! LaTeX Error: Too deeply nested.

What itemize's four default markers really are

itemize's markers live in four macros, one per level: \labelitemi, \labelitemii, \labelitemiii, \labelitemiv (the trailing i / ii / iii / iv being Roman numerals for levels 1 to 4). Their definitions in the standard classes are in the table below, and all four begin with \labelitemfont — a small hook defined in article.cls as \normalfont, which guarantees that the marker is set in the body typeface even where the surrounding text is italic or bold. Level 2 alone follows \labelitemfont with a further \bfseries, so its en dash is set bold. That is why it looks heavier than its neighbours.

To change the marker for a whole level, redefine the matching macro with \renewcommand, placed in the preamble or just before the scope you want it in. One thing to watch: these macros do not enter math mode. Unless you write the dollars yourself, as in $\diamond$, \diamond is unusable in text and raises an error. The usual alternatives are $\diamond$ (◇), $\ast$ (∗), $\cdot$ (·) and $\triangleright$ (▷); load the pifont package and ornaments such as \ding{"6C} become available too. Be careful not to get carried away, though: elaborate markers make the levels harder to tell apart, so changing level 1 only is usually the safe move.

% the whole of level 1 becomes a diamond -- note the explicit math shift
\renewcommand{\labelitemi}{$\diamond$}

% or, with enumitem, the same thing scoped to one list
\begin{itemize}[label=$\diamond$]
  \item this list only
\end{itemize}

Overriding one entry's label with \item[...]

To change the marker for one entry only, give a label in square brackets right after \item: \item[$\star$] makes that entry's marker a star, \item[--] a dash. And here one widely held belief needs correcting. A bracketed label is not set bold. Write \item[Word] inside an itemize and the resulting PDF embeds only the roman text font; no bold face appears at all. The \makelabel of itemize and enumerate is defined as \hss\llap{...}, so the label is merely set flush right inside its box, overhanging to the left if it is too wide — the typeface is never touched. Bold happens only in description, and only because \descriptionlabel carries a \bfseries.

\theenumi versus \labelenumi: the number and its dressing

\theenumi decides how the number is represented — 1, or I, or a — while \labelenumi decides how that number is dressed at the head of the line, with surrounding parentheses or a period. enumerate uses one counter per level, enumi, enumii, enumiii, enumiv; \theenumi turns the counter's value into characters, and \labelenumi calls that and adds the punctuation. It is a two-stage arrangement. The standard-class defaults are in the table below, and they are asymmetric: level 2 alone gets parentheses, the rest get a period.

The two-stage design shows its worth in cross-references. What \ref returns is the bare representation with \labelenumi's dressing stripped off — that is, \theenumi. So if you redefine \labelenumi as (\theenumi) to print (1) at the head of the line, \ref still returns an unparenthesised 1; to write “see step (1)” you must add the brackets at the reference, or use enumitem's ref=. More precisely, LaTeX builds the reference string by prefixing \theenumi with \p@enumi, and the standard classes define \p@enumii as \theenumi and \p@enumiii as \theenumi(\theenumii). That is why a \ref to a level-2 item comes back as “1a”, carrying the parent number with it. Creating and stepping counters in general is the business of the counters and lengths page.

% change only the representation: the head reads I. II. III. and \ref gives I
\renewcommand{\theenumi}{\Roman{enumi}}

% change only the dressing: the head reads (1) but \ref still gives a bare 1
\renewcommand{\labelenumi}{(\theenumi)}

The counter-representation commands, and where they give out

To choose how a number looks inside \theenumi or \labelenumi, use LaTeX's six standard counter-representation commands. Each takes a counter name as its argument, as in \Roman{enumi}, and prints that counter's value in the chosen form. What matters is that three of them have a ceiling. \alph and \Alph past 26, and \fnsymbol outside 1–9, both stop with ! LaTeX Error: Counter too large. A list of 27 entries labelled label=\alph* will fail at the twenty-seventh, every time.

The awkward part is that some of these fail loudly and some fail silently. \alph{0} and \roman{0} return an empty string without a word of complaint, so referring to a counter still sitting at zero produces a list whose labels have simply vanished, with no clue as to why. \alph{27}, by contrast, at least stops with Counter too large. The nine symbols of \fnsymbol — exactly the sequence in the definition of \@fnsymbol — are a footnote series, and pressing them into service as list labels breaks at the tenth entry. Reserve them for short annotated lists.

Writing it with enumitem's label=: building a label out of counters

Redefining macros is powerful but unwieldy when the styling has to differ from list to list. In most cases enumitem's label= reads better, so try that first. Inside label=, the starred forms \arabic*, \alph*, \Alph*, \roman* and \Roman* stand for the current counter at that level. The unstarred \arabic{...} still works alongside them, and mixing the two lets you build a label out of some other counter: write label=\thesection.\arabic* and the entries are numbered “3.1”, “3.2” with the section number in front, following the section automatically if you move it.

\usepackage{enumitem}
\setlist[enumerate,1]{label=\Roman*.}    % level 1 becomes I. II. III.
\setlist[enumerate,2]{label=(\alph*)}    % level 2 becomes (a) (b)
\setlist[itemize,1]{label=$\diamond$}    % itemize level 1 becomes a diamond

% a label built from another counter
\begin{enumerate}[label=\thesection.\arabic*, leftmargin=*]
  \item numbered 3.1 inside section 3
\end{enumerate}

% label*= accumulates onto the parent label: 1. then 1.1. 1.2.
\begin{enumerate}[label*=\arabic*.]
  \item one
  \begin{enumerate}[label*=\arabic*.]
    \item one-point-one
  \end{enumerate}
\end{enumerate}

label*= chains onto the parent's label, so nesting accumulates as 1., 1.1., 1.2. — compiled and confirmed. Note, though, that the chaining applies only to the printed label: the parent number is not added to cross-references automatically. To get a reference like “1.a” you must spell it out with ref=, as in ref=\theenumi.\alph*. And whenever you hand over a wide label, remember to add leftmargin=*: the default label box is only 20pt, so a long label like \thesection.\arabic* will overhang to the left. To apply the styling throughout, name the type and level, as in \setlist[enumerate,1]{...}.

Loading the package as \usepackage[shortlabels]{enumitem} also lets you write the terse \begin{enumerate}[(1)] of the old enumerate package. Placing A, a, I, i or 1 as the first element in the brackets means \Alph*, \alph*, \Roman*, \roman* or \arabic* respectively.

Too deeply nested: the real limit on nesting

People often say LaTeX lists can only nest four deep. That is only half right. There are two separate ceilings, and reading latex.ltx shows the structure. itemize keeps its depth in \@itemdepth and enumerate in \@enumdepth — two independent counters — and each calls \@toodeep once its own counter exceeds 3. So the four-level limit applies only when you stack the same environment. On top of that, \list itself carries a global gate, \ifnum \@listdepth >5, and that one does not care what type the lists are.

Compiled, that is exactly what happens. Stack five itemize environments and the fifth raises ! LaTeX Error: Too deeply nested. Five enumerate environments do the same. But alternate itemize and enumerate and six levels produce no error at all; only the seventh raises it — and this time it is \@listdepth doing the stopping. So the practical ceiling is four levels of one kind, six if you alternate. Treat that as knowledge rather than as permission, though: a six-deep nest is essentially never readable. When you genuinely need that much depth, reach for headings such as \subsubsection, or for the easylist package, rather than for lists.

The awkward part of this error is that it does not stop the typesetting. The depth test in the definition of \itemize has the shape \ifnum ... \@toodeep \else ... \fi, so when the limit is exceeded LaTeX simply does not begin a list and lets the body flow straight through. The result is a confusing kind of breakage: the error is logged once, the PDF is produced, and the entries at that level come out as ordinary running text. If you see Too deeply nested in the log, fix the passage even though a PDF appeared. One more consequence: defining a \labelitemv for a fifth level accomplishes nothing, because the test rejects the list before that level is ever reached.