tikz.dev / nicematrix Manual

The nicematrix package

The package nicematrix

Enhanced arrays with the help of PGF/TikZ, version 7.12 (2026/10/07)
Unofficial HTML Version
This HTML version of the documentation is maintained by Dominik Peters, and is generated from the LaTeX sources of the manual.
Author of the nicematrix manual: F. Pantigny.
github.com/fpantigny/nicematrix

Abstract

The LaTeX package nicematrix provides new environments similar to the classical environments {tabular}, {array} and {matrix} of array and amsmath but with extended features.

Compiled outputCompiled outputCompiled output

Contents

1The environments of this package

2The vertical space between the rows

3The vertical position of the arrays

4The blocks

  1. 4.1General case
  2. 4.2The mono-column blocks
  3. 4.3The mono-row blocks
  4. 4.4The mono-cell blocks
  5. 4.5Horizontal position of the content of the block
  6. 4.6Vertical position of the content of the block
  7. 4.7\\ and & in the blocks
  8. 4.8The key create-blocks-in-col

5The rules

  1. 5.1Some differences with the classical environments
  2. 5.2The thickness and the color of the rules
  3. 5.3The tools of nicematrix for the rules

6The color of the background of the rows and columns

  1. 6.1Use of colortbl
  2. 6.2The tools of nicematrix in the \CodeBefore
  3. 6.3Color tools to be used inside the tabular
  4. 6.4The special color “nocolor”

7The command \RowStyle

8The width of the columns

  1. 8.1Basic tools
  2. 8.2The columns V of varwidth
  3. 8.3The columns X

9The exterior rows and columns

10Dotted leaders in the matrices

  1. 10.1The option xdots/nullify
  2. 10.2The commands \Hdotsfor and \Vdotsfor
  3. 10.3How to generate the dotted leaders transparently
  4. 10.4The labels of the dotted leaders
  5. 10.5Customisation of the dotted leaders
  6. 10.6The dotted leaders and the rules
  7. 10.7The commands \Hbrace and \Vbrace

11Delimiters in the preamble of the environment

12The \CodeAfter

  1. 12.1The command \line in the \CodeAfter
  2. 12.2The command \SubMatrix in the \CodeAfter (and the \CodeBefore)
  3. 12.3The commands \OverBrace and \UnderBrace in the \CodeAfter
  4. 12.4The command \TikzEveryCell

13Captions and notes in the tabulars

  1. 13.1Caption of a tabular
  2. 13.2The footnotes
  3. 13.3The notes of tabular
  4. 13.4Customisation of the tabular notes

14Other features

  1. 14.1Trees
  2. 14.2The key rounded-corners of the environments
  3. 14.3The command \ShowCellNames
  4. 14.4Use of the column type S of siunitx
  5. 14.5Default column type in {NiceMatrix}
  6. 14.6The command \rotate
  7. 14.7The key small
  8. 14.8\AutoNiceMatrix and the counters iRow and jCol
  9. 14.9The key light-syntax
  10. 14.10Color of the delimiters
  11. 14.11The environment {NiceArrayWithDelims}
  12. 14.12The command \OnlyMainNiceMatrix

15Explicit use of TikZ with nicematrix

  1. 15.1The nodes corresponding to the contents of the cells
  2. 15.2The “medium nodes” and the “large nodes”
  3. 15.3The nodes which indicate the position of the rules
  4. 15.4The nodes corresponding to the command \SubMatrix

16API for the developers

  1. 16.1Public sets of keys
  2. 16.2\CodeBefore and \CodeAfter

17Technical remarks

  1. 17.1Diagonal dotted leaders
  2. 17.2The “empty” cells
  3. 17.3The option exterior-arraycolsep
  4. 17.4Incompatibilities
  5. 17.5Compatibility with the Tagging Project of LaTeX

18Examples

  1. 18.1Notes in the tabulars
  2. 18.2Use of the key “tikz” of the command \Block
  3. 18.3Use with tcolorbox
  4. 18.4A sign chart
  5. 18.5A variation table
  6. 18.6Example of description of a table of a database
  7. 18.7Use of the key borders of the command \Block
  8. 18.8Leaders in the matrices
  9. 18.9How the illustrate the numbers of rows and columns in a matrix
  10. 18.10Stacks of matrices
  11. 18.11How to highlight cells of a matrix
  12. 18.12A triangular tabular

History

Introduction

Compiled output
Compiled output

The package nicematrix is entirely contained in the file nicematrix.sty. This file may be put in the current directory or in a texmf tree. However, the best is to install nicematrix with a TeX distribution such as MiKTeX, TeX Live or MacTeX.

Remark

If you use LaTeX via Internet with, for example, Overleaf or TeXPage, you can upload the file nicematrix.sty in the repertory of your project in order to take full advantage of the latest version de nicematrix.1

This package can be used with xelatex, lualatex, pdflatex but also by the classical workflow latex-dvips-ps2pdf (or Adobe Distiller). However, the file nicematrix.dtx of the present documentation should be compiled with LuaLaTeX.

This package requires and loads the packages array, amsmath, pgfcore and the module shapes of pgf (tikz, which is a layer over pgf, is not loaded). The final user only has to load the package with \usepackage{nicematrix}.

The idea of nicematrix is to create pgf nodes under the cells and the positions of the rules of the tabular created by array and to use these nodes to develop new features. As usual with pgf, the coordinates of these nodes are written in the aux file to be used on the next compilation and that’s why nicematrix may need several compilations2. One must not use the command \nofiles (which prevents the creation of the aux file).

Most features of nicematrix may be used without explicit use of pgf or TikZ (which, in fact, is not loaded by default).

A command \NiceMatrixOptions is provided to fix the options (the scope of the options fixed by this command is the current TeX group: they are semi-global).

1 The latest version of the file nicematrix.sty may be downloaded on the GitHub depot of nicematrix:
https://github.com/fpantigny/nicematrix/releases

2 If you use Overleaf, Overleaf will do automatically a sufficient number of compilations (by using latexmk).