> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/commands/02-environments.md). # 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: ```latex \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.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Simple+environment+example\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bcenter%7D%0AThis+is+a+demonstration+of+the+%5Ctexttt%7Bcenter%7D+environment.+%0AThis+paragraph+of+text+will+be+%5Ctextit%7Bcentred%7D+because+it+is+%0Acontained+within+a+special+environment.+Environments+provide+%0Aan+efficient+way+to+modify+blocks+of+text+within+your+document.%0A%5Cend%7Bcenter%7D%0A%5Cend%7Bdocument%7D) This example produces the following output: ![Image showing the center alignment](/files/tb3G59dPRtAMqEuLfZVu) ## 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](/latex/figures-and-tables/01-tables.md) article for more information. ```latex \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.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Simple+tabular+environment+example\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Btabular%7D%7B+c+c+c+%7D+%0A++cell1+%26+cell2+%26+cell3+%5C%5C+%0A++cell4+%26+cell5+%26+cell6+%5C%5C+%0A++cell7+%26+cell8+%26+cell9+%5C%5C+%0A+%5Cend%7Btabular%7D%0A%5Cend%7Bdocument%7D) This example produces the following output: ![Example of the tabular environment](/files/WkAqZwXpRJU2LueVqcrm) 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](#defining-simple-environments); * `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: ```latex \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.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Creating+a+new+environment\&snip=%5Cdocumentclass%7Barticle%7D%0A%25We+can+define+the+environment+in+the+preamble%0A%5Cnewenvironment%7Bboxed%7D%0A++++%7B%5Cbegin%7Bcenter%7D%0A++++%5Cbegin%7Btabular%7D%7B%7Cp%7B0.9%5Ctextwidth%7D%7C%7D%0A++++%5Chline%5C%5C%0A++++%7D%0A++++%7B+%0A++++%5C%5C%5C%5C%5Chline%0A++++%5Cend%7Btabular%7D+%0A++++%5Cend%7Bcenter%7D%0A++++%7D%0A%25%0A%5Cbegin%7Bdocument%7D%0ANow+we+can+use+the+%5Ctexttt%7Bboxed%7D+environment+in+our+document%3A%0A%0A%5Cbegin%7Bboxed%7D%0AThis+text+is+formatted+within+the+%5Ctexttt%7Bboxed%7D+environment.%0A%5Cend%7Bboxed%7D%0A%0AThis+text+is+typeset+outside+the+%5Ctexttt%7Bboxed%7D+environment.%0A%5Cend%7Bdocument%7D) This example produces the following output: ![Demonstrating a custom LaTeX environment](/files/quE1GcRKF0XyyiqSFltP) 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): ```latex \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): ```latex \\\\\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: ```latex \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: ```latex \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.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Environment+with+an+optional+argument\&snip=%5Cdocumentclass%7Barticle%7D%0A%25+Note+the+default+value+for+the+first%0A%25+argument+is+provided+by+%5BThis+is+a+box%5D%0A%5Cnewenvironment%7Bboxed%7D%5B2%5D%5BThis+is+a+box%5D%0A++++%7B%5Cbegin%7Bcenter%7D%0A++++Argument+1+%28%5C%231%29%3D%231%5C%5C%5B1ex%5D%0A++++%5Cbegin%7Btabular%7D%7B%7Cp%7B0.9%5Ctextwidth%7D%7C%7D%0A++++%5Chline%5C%5C%0A++++Argument+2+%28%5C%232%29%3D%232%5C%5C%5B2ex%5D%0A++++%7D%0A++++%7B+%0A++++%5C%5C%5C%5C%5Chline%0A++++%5Cend%7Btabular%7D+%0A++++%5Cend%7Bcenter%7D%0A++++%7D%0A%5Cbegin%7Bdocument%7D%0A%5Ctextbf%7BExample+1%7D%3A+Use+the+default+value+for+the+first+argument%3A%0A+%0A%5Cbegin%7Bboxed%7D%7BSome+preliminary+text%7D%0AThis+text+is+%5Ctextit%7Binside%7D+the+environment.%0A%5Cend%7Bboxed%7D%0A%0AThis+text+is+%5Ctextit%7Boutside%7D+the+environment.%0A%0A%5Cvskip12pt%0A%0A%5Ctextbf%7BExample+2%7D%3A+Provide+a+value+for+the+first+argument%3A%0A+%0A%5Cbegin%7Bboxed%7D%5BThis+is+not+the+default+value%5D%7BSome+more+preliminary+text%7D%0AThis+text+is+still+%5Ctextit%7Binside%7D+the+environment.%0A%5Cend%7Bboxed%7D%0A%0AThis+text+is+also+%5Ctextit%7Boutside%7D+the+environment.%0A%5Cend%7Bdocument%7D) This example produces the following output: ![Environment with an optional parameter](/files/ttLn4A2ISi9gwJHxCJrP) ### Numbered environments Numbered environments can be created either manually or directly with the command `\newtheorem`, as demonstrated by the following example: ```latex \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](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Creating+a+numbered+environment\&snip=%5Cdocumentclass%7Barticle%7D%0A%25+Define+our+numbered+environment+within+the+preamble%0A%5Cnewcounter%7Bexample%7D%5Bsection%5D%0A%5Cnewenvironment%7Bexample%7D%5B1%5D%5B%5D%7B%5Crefstepcounter%7Bexample%7D%5Cpar%5Cmedskip%0A+++%5Cnoindent+%5Ctextbf%7BExample%7E%5Ctheexample.+%231%7D+%5Crmfamily%7D%7B%5Cmedskip%7D%0A%0A%25+Another+numbered+environment+defined+with+%5Cnewtheorem%0A%5Cusepackage%7Bamsmath%7D+%25+For+the+%5Cnewtheorem+command%0A%5Cnewtheorem%7BSampleEnv%7D%7BSample+Environment%7D%5Bsection%5D%0A%5Cbegin%7Bdocument%7D%0A%0A%5Csection%7BUser-defined+numbered+environments%7D%0A%0A%5Cbegin%7Bexample%7D%0AFirst+user-defined+numbered+environment+%28number+%5Ctheexample%29.%0A%5Cend%7Bexample%7D%0A%0A%5Cbegin%7Bexample%7D%0ASecond+user-defined+numbered+environment+%28number+%5Ctheexample%29.%0A%5Cend%7Bexample%7D%0A%0A%5Csection%7BMore+user-defined+numbered+environments%7D%0ANote+how+the+example+numbering+has+restarted+at+1%3A%0A%0A%5Cbegin%7Bexample%7D%0AFirst+user-defined+numbered+environment+%28number+%5Ctheexample%29.%0A%5Cend%7Bexample%7D%0A%0A%5Cbegin%7BSampleEnv%7D%0AUser-defined+environment+created+with+the+%5Cverb%7C%5Cnewtheorem%7C+command.%0A%5Cend%7BSampleEnv%7D%0A%5Cend%7Bdocument%7D) This example produces the following output: ![Example showing user-defined numbered environments](/files/f5m8WrkUBNAUAce6vNVY) #### 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](/latex/formatting/10-counters.md) 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](https://ctan.org/pkg/amsthm?lang=en), along with `amsmath`, provide useful extra definitions alongside `\newtheorem`; see [Theorems and proofs](/latex/field-specific/01-theorems-and-proofs.md) 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](#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). ```latex \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.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Redefining+an+existing+environment\&snip=%5Cdocumentclass%7Barticle%7D%0A%25+Redefine+the+environment+in+the+preamble%0A%5Crenewenvironment%7Bitemize%7D%0A%7B%5Cbegin%7Bcenter%7D%5Cem%7D%0A%7B%5Cend%7Bcenter%7D%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5Cbegin%7Bitemize%7D%0AWe+have+redefined+the+%5Ctexttt%7Bitemize%7D+environment+so+that+any+text+%0Awithin+it+is+centred+and+emphasised+%28italicized%29.+It+no+longer+creates%0Aa+bulleted+list---this+is+only+an+example+and+not+intended+for+use+%0Ain+real+documents%21%0A%5Cend%7Bitemize%7D%0A%5Cend%7Bdocument%7D) This example produces the following output: ![Example with a redefined itemize environment](/files/x4lqUkMi1J0Gl5G77HNe) ## Further reading For more information see: * [Commands](/latex/commands/01-commands.md) * [Understanding packages and class files](/latex/class-files/01-understanding-packages-and-class-files.md) * [Writing your own package](/latex/class-files/03-writing-your-own-package.md) * [Writing your own class](/latex/class-files/04-writing-your-own-class.md) * [Lengths in LaTeX](/latex/formatting/01-lengths-in-latex.md) * [Using colours in LaTeX](/latex/formatting/13-using-colors-in-latex.md) * [Page size and margins](/latex/formatting/07-page-size-and-margins.md) * [List of packages and class files](/latex/class-files/02-overleaf-and-tex-live.md) * [The not so short introduction to LaTeX2ε](http://www.ctan.org/tex-archive/info/lshort/) * [LaTeX/Creating\_Packages on WikiBooks](http://en.wikibooks.org/wiki/LaTeX/Creating_Packages) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/commands/02-environments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.