Environments

Environments are used to format blocks of text in a LaTeX documents. This article explains how to use environments and how to define new ones.

Introduction

Below you can see a very simple example on how to use an environment.

\begin{center}
This text will be centred since it is inside a special 
environment. Environments provide a efficient way of modifying 
blocks of text within your document.
\end{center}

In this example all the text inside the center environment is centred.

  Open an example in Overleaf

Environments

Environments are delimited by an opening tag \begin and a closing tag \end. Everything inside those tags will be formatted in a special manner depending on the type of the environment.

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

This environment tabular takes an additional argument { c c c } to determine the alignment of the cells (See the Tables article for more information).

Environments may accept optional arguments that usually are passed inside brackets []

  Open an example in Overleaf

Defining a new environment

Just as with commands, you can define new environments.

Defining simple environments

The new environment definition is achieved by the \newenvironment tag:

\newenvironment{boxed}
    {\begin{center}
    \begin{tabular}{|p{0.9\textwidth}|}
    \hline\\
    }
    { 
    \\\\\hline
    \end{tabular} 
    \end{center}
    }
%--------------------------------------------------

Below this line a boxed environment is used

\begin{boxed}
This is the text formatted by the boxed environment
\end{boxed}

This text is again outside the environment

This environment will draw a box around the text within.

Right after the \newenvironment, in between braces, you must write the name of the environment, boxed in the example. Below that are two pairs of braces. Inside the first pair of braces is set what your new environment will do before the text within, then inside the second pair of braces declare what your new environment will do after the text.

In the example, in between the before braces a tabular environment is started to draw the vertical lines and a horizontal line is drawn. Inside the after braces another horizontal line is drawn and the tabular environment is closed. Additionally it's enclosed by a center environment.

  Open an example in Overleaf

Defining environments with parameters

Environments that accept parameters can also be defined. Let's enhance the previous example to put a title for the box:

\newenvironment{boxed}[1]
    {\begin{center}
    #1\\[1ex]
    \begin{tabular}{|p{0.9\textwidth}|}
    \hline\\
    }
    { 
    \\\\\hline
    \end{tabular} 
    \end{center}
    }
%--------------------------------------------------

Below this line a boxed environment is used

\begin{boxed}{Title of the Box}
This is the text formatted by the boxed environment
\end{boxed}

This text is again outside the environment

As you see, the command definition is almost the same as in the example of the previous section, except for [1] that sets the number of parameters to be used in the environment; and #1\\[1ex] that inserts the parameter at the top of the box and also separates the title from the box by a 1ex blank space.

So you can specify how many parameters an environment takes using an optional argument to \newenvironment. In fact you can use two optional arguments, the first specifying the number of parameters, the second defining a default value for the first one which then will be an optional parameter. So

\newenvironment{Example}[2][Example]
    {This is an #1. You gave #2 as an argument. The rest will be bold: \bfseries}
    {}

defines a new environment called Example which takes one optional and one mandatory argument. The default value for the optional one will be "Example". You can use this environment with \begin{Example}[inspiring example]{argument} or with \begin{Example}{argument}. Note that you can only access the parameters inside the code definition for the code used before the contents of the environment.

Numbered environments

Numbered environments can be created either manually or directly with the command \newtheorem. These commands can also include a \label tag for cross reference.

%In the preamble
---------------------------------
%Numbered environment
\newcounter{example}[section]
\newenvironment{example}[1][]{\refstepcounter{example}\par\medskip
   \noindent \textbf{Example~\theexample. #1} \rmfamily}{\medskip}


%Numbered environment defined with Newtheorem
\usepackage{amsmath}
\newtheorem{SampleEnv}{Sample Environment}[section]
--------------------------------------------------------------------


\begin{example}
User-defined numbered environment
\end{example}

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

In the manually-defined environment the command \newcounter{example}[section] creates a counter called example that will be reset every time a new section is started. The counter is incremented by one with \refstepcounter{example} within the environment definition, and its value is printed using \theexample. See the article about counters to learn more.

Alternatively, the command \newtheorem creates a numbered environment directly. This command takes three parameters: the name of the new environment, the text to be printed in blackbold font at the beginning of the line, and finally an optional parameter that determines when the counter is reset; and if it's used the counter gets preceded by that reset counter's value. In the example the arguments are SampleEnv, Sample Environment and section respectively. The amsthm (and similarly amsmath) package provides useful extra definitions alongside \newtheorem; see Theorems and proofs for further details.

  Open an example in Overleaf

Overwriting existing environments

Environments can be overwritten with \renewenvironment. The syntax is equivalent to that of the \newenvironment definition.

\renewenvironment{itemize}
{\begin{center}\em}
{\end{center}}
%--------------------------------------------------

\begin{itemize}
This is now an environment that centres the text and
emphasizes it.
\end{itemize}

In this example we overwrite the itemize environment so instead of listing elements, this new environment centres and emphasizes the text within; resulting in italicizing it because of the standard rules for \em and \emph. Note that this is only done as an example and should be considered a bad idea in a real document.

  Open an example in Overleaf

Reference guide

• an environment is used with a matching pair of \begin and \end statements. Both \begin and \end take the name of the environment as argument in curly braces. The \begin statement might have additional mandatory and/or optional arguments.
• \newenvironment{<name>}{<begin code>}{<end code>} defines a new environment called <name>. At \begin{<name>} the code <begin code> will be executed and at \end{<name>} the <end code> is inserted.
• \renewenvironment{<name>}{<begin code>}{<end code>} can be used to change the existing definition of an environment.

Both with \newenvironment and \renewenvironment you can specify how many arguments the environment should take using \newenvironment{<name>}[<number>] and you can specify an optional argument using \newenvironment{<name>}[<number>][<default>].

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