Environments

LaTeX environments are used to apply specific typesetting effect(s) to a section of your document’s content. This article explains how to use existing environments and define new ones.

Introduction

An environment starts with \begin{name} and ends with \end{name}:

\begin{name}
Your content here...
...goes here...
\end{name}

where “name” is the name of the environment being used—such as the following example using “center” to format (center) a paragraph of text:

\documentclass{article}
\begin{document}
\begin{center}
This is a demonstration of the \texttt{center} environment. 
This paragraph of text will be \textit{centred} because it is 
contained within a special environment. Environments provide 
an efficient way to modify blocks of text within your document.
\end{center}
\end{document}

 Open this example in Overleaf.

This example produces the following output:

Environments

The following example uses the tabular environment to typeset a small table. tabular takes an additional argument { c c c } which defines the alignment of the cells—see the Tables article for more information.

\documentclass{article}
\begin{document}
\begin{tabular}{ c c c } 
  cell1 & cell2 & cell3 \\ 
  cell4 & cell5 & cell6 \\ 
  cell7 & cell8 & cell9 \\ 
 \end{tabular}
\end{document}

 Open this example in Overleaf.

This example produces the following output:

Some environments accept optional arguments which are usually passed inside brackets ([...]).

Defining a new environment

To define a new environment use the \newenvironment command which has the general form:

\newenvironment{name}[numarg][optarg_default]{begin_def}{end_def}

where:

• name is the name of this user-defined argument;
• numarg is the number of arguments, from 1 to 9, this environment accepts. If [numarg] is omitted then the environment does not accept any arguments—such as the boxed environment defined in the next example;
• optarg_default makes the first argument optional and provides a default value—i.e., it is the value used if an optional argument value is not provided;
• begin_def is LaTeX code executed when the environment starts (opens), i.e., when you write \begin{name}. Within this code you can use arguments accepted by the environment—note that the optional argument is #1 and the remaining arguments are accessed using #2 to #numarg;
• end_def is LaTeX code executed when the environment ends (closes); i.e., when you write \end{name}. You cannot use any of the arguments within this code section.

Defining simple environments

In this first example, we define the boxed environment which does not take any arguments. It draws a box around text contained within the environment:

\documentclass{article}
%We can define the environment in the preamble
\newenvironment{boxed}
    {\begin{center}
    \begin{tabular}{|p{0.9\textwidth}|}
    \hline\\
    }
    { 
    \\\\\hline
    \end{tabular} 
    \end{center}
    }
%
\begin{document}
Now we can use the \texttt{boxed} environment in our document:

\begin{boxed}
This text is formatted within the \texttt{boxed} environment.
\end{boxed}

This text is typeset outside the \texttt{boxed} environment.
\end{document}

 Open this example in Overleaf.

This example produces the following output:

If we compare our definition of boxed with the general form of \newenvironment we can see:

• name is boxed;
• neither [numarg] or [optarg_default] are provided because this environment does not take any arguments;
• begin_def is the LaTeX code—provided between a pair of braces {...}—which is executed when the environment starts (opens):

\begin{center}
    \begin{tabular}{|p{0.9\textwidth}|}
    \hline\\

• end_def is the LaTeX code—provided between a pair of braces {...}—which is executed when the environment stops (closes):

    \\\\\hline
    \end{tabular} 
    \end{center}

In the example, begin_def starts a center environment and within that a tabular environment is opened to draw vertical lines and a horizontal line around the text we place in the environment. end_def draws another horizontal line then closes the tabular and center environments.

Defining environments which take arguments

Let’s enhance the previous example to do the following:

• use an optional argument to typeset a title. If a title is not provided, use the default value This is a box;
• use a second argument which contains material to typeset ahead of the text we provide within the environment itself.

So we have 2 arguments:

• the first (argument 1) is optional;
• the second (argument 2) is not.

This means numarg=2.

We can use the following definition of our updated boxed environment:

\newenvironment{boxed}[2][This is a box]
    {\begin{center}
    Argument 1 (\#1)=#1\\[1ex]
    \begin{tabular}{{{!}}p{0.9\textwidth}{{!}}}
    \hline\\
    Argument 2 (\#2)=#2\\[2ex]
    }
    { 
    \\\\\hline
    \end{tabular} 
    \end{center}
    }

This enhanced version differs from the original in the following ways:

• [numarg] is present and has the value 2;
• [optarg_default] is also present, making the first argument optional with a default value This is a box.

The following example demonstrates some uses of our upgraded boxed environment:

\documentclass{article}
% Note the default value for the first
% argument is provided by [This is a box]
\newenvironment{boxed}[2][This is a box]
    {\begin{center}
    Argument 1 (\#1)=#1\\[1ex]
    \begin{tabular}{|p{0.9\textwidth}|}
    \hline\\
    Argument 2 (\#2)=#2\\[2ex]
    }
    { 
    \\\\\hline
    \end{tabular} 
    \end{center}
    }
\begin{document}
\textbf{Example 1}: Use the default value for the first argument:
 
\begin{boxed}{Some preliminary text}
This text is \textit{inside} the environment.
\end{boxed}

This text is \textit{outside} the environment.

\vskip12pt

\textbf{Example 2}: Provide a value for the first argument:
 
\begin{boxed}[This is not the default value]{Some more preliminary text}
This text is still \textit{inside} the environment.
\end{boxed}

This text is also \textit{outside} the environment.
\end{document}

 Open this example in Overleaf.

This example produces the following output:

Numbered environments

Numbered environments can be created either manually or directly with the command \newtheorem, as demonstrated by the following example:

\documentclass{article}
% Define our numbered environment within the preamble
\newcounter{example}[section]
\newenvironment{example}[1][]{\refstepcounter{example}\par\medskip
   \noindent \textbf{Example~\theexample. #1} \rmfamily}{\medskip}

% Another numbered environment defined with \newtheorem
\usepackage{amsmath} % For the \newtheorem command
\newtheorem{SampleEnv}{Sample Environment}[section]
\begin{document}

\section{User-defined numbered environments}

\begin{example}
First user-defined numbered environment (number \theexample).
\end{example}

\begin{example}
Second user-defined numbered environment (number \theexample).
\end{example}

\section{More user-defined numbered environments}
Note how the example numbering has restarted at 1:

\begin{example}
First user-defined numbered environment (number \theexample).
\end{example}

\begin{SampleEnv}
User-defined environment created with the \verb|\newtheorem| command.
\end{SampleEnv}
\end{document}

 Open this example in Overleaf

This example produces the following output:

Some notes

• In the manually-defined example environment the command \newcounter{example}[section] creates a counter, also called example. The example counter is:
  • incremented by 1 by using \refstepcounter{example} within the environment definition;
  • reset every time a new \section{...} is started;
  • a variable whose current value can be typeset using \theexample. See the article about counters to learn more.

• The command \newtheorem directly creates a numbered environment and takes three parameters:
  • the name of the new environment: SampleEnv in our example;
  • the text to be printed in bold at the beginning of the line: Sample Environment in our example;
  • an optional parameter which determines when the counter is reset; and if it’s used the counter gets preceded by that reset counter’s value: section in our example.

The amsthm package, along with amsmath, provide useful extra definitions alongside \newtheorem; see Theorems and proofs for further details.

Redefining existing environments

Environments can be redefined using \renewenvironment whose syntax is the same as \newenvironment—see the section Defining a new environment for an explanation of the various parameters:

\newenvironment{name}[numarg][optarg_default]{begin_def}{end_def}

The next example redefines the itemize environment—this is only an example to illustrate the process, it should not be considered within a real document. The new itemize environment no longer produces a bulleted list; instead, it centres and emphasizes (italicizes) the text within it (using the \em command).

\documentclass{article}
% Redefine the environment in the preamble
\renewenvironment{itemize}
{\begin{center}\em}
{\end{center}}
\begin{document}

\begin{itemize}
We have redefined the \texttt{itemize} environment so that any text 
within it is centred and emphasised (italicized). It no longer creates
a bulleted list---this is only an example and not intended for use 
in real documents!
\end{itemize}
\end{document}

 Open this example in Overleaf.

This example produces the following output:

Further reading

For more information see:

• Commands
• Understanding packages and class files
• Writing your own package
• Writing your own class
• Lengths in LaTeX
• Using colours in LaTeX
• Page size and margins
• List of packages and class files
• The not so short introduction to LaTeX2ε
• LaTeX/Creating_Packages on WikiBooks