matplotlib · timhoffm · Aug 7, 2026 · Aug 1, 2026 · Aug 4, 2026
diff --git a/galleries/examples/lines_bars_and_markers/linestyles.py b/galleries/examples/lines_bars_and_markers/linestyles.py
@@ -1,15 +1,23 @@
 """
+.. _linestyle_def:
+
 ==========
 Linestyles
 ==========
 
-Simple linestyles can be defined using the strings "solid", "dotted", "dashed"
-or "dashdot". More refined control can be achieved by providing a dash tuple
-``(offset, (on_off_seq))``. For example, ``(0, (3, 10, 1, 15))`` means
-(3pt line, 10pt space, 1pt line, 15pt space) with no offset, while
-``(5, (10, 3))``, means (10pt line, 3pt space), but skip the first 5pt line.
-See also `.Line2D.set_linestyle`.  The specific on/off sequences of the
-"dotted", "dashed" and "dashdot" styles are configurable:
+Linestyles can be specified in two ways:
+
+* **Named linestyles**: "solid", "dotted", "dashed", "dashdot" and their
+  short forms "-", ":", "--", "-."
+* **Parametrized linestyles**: a dash tuple ``(offset, (on_off_seq))``. For example,
+  ``(0, (3, 10, 1, 15))`` means (3pt line, 10pt space, 1pt line, 15pt space) with no
+  offset, while ``(5, (10, 3))``, means (10pt line, 3pt space), but skip the first
+  5pt line.
+
+See also `.Line2D.set_linestyle`.
+
+The specific on/off sequences of the "dotted", "dashed" and "dashdot" styles are
+configurable:
 
 * :rc:`lines.dotted_pattern`
 * :rc:`lines.dashed_pattern`

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1998,7 +1998,7 @@ def acorr(self, x, **kwargs):
 
         Other Parameters
         ----------------
-        linestyle : `~matplotlib.lines.Line2D` property, optional
+        linestyle : :mpltype:`linestyle`, optional
             The linestyle for plotting the data points.
             Only used if *usevlines* is ``False``.
 
@@ -2078,7 +2078,7 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
 
         Other Parameters
         ----------------
-        linestyle : `~matplotlib.lines.Line2D` property, optional
+        linestyle : :mpltype:`linestyle`, optional
             The linestyle for plotting the data points.
             Only used if *usevlines* is ``False``.
 
@@ -4027,11 +4027,8 @@ def errorbar(self, x, y, yerr=None, xerr=None,
             The linewidth of the errorbar lines. If None, the linewidth of
             the current style is used.
 
-        elinestyle : str or tuple, default: 'solid'
+        elinestyle : :mpltype:`linestyle`, default: 'solid'
            The linestyle of the errorbar lines.
-           Valid values for linestyles include {'-', '--', '-.',
-            ':', '', (offset, on-off-seq)}. See `.Line2D.set_linestyle` for a
-            complete description.
 
         capsize : float, default: :rc:`errorbar.capsize`
             The length of the error bar caps in points.

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -3608,8 +3608,8 @@ def tick_params(self, axis='both', **kwargs):
             Transparency of gridlines: 0 (transparent) to 1 (opaque).
         grid_linewidth : float
             Width of gridlines in points.
-        grid_linestyle : str
-            Any valid `.Line2D` line style spec.
+        grid_linestyle : :mpltype:`linestyle`
+            Linestyle of the gridlines.
 
         Examples
         --------

diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -675,7 +675,7 @@ def set_linestyle(self, ls):
 
         Parameters
         ----------
-        ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) or list thereof
+        ls : :mpltype:`linestyle` or list of :mpltype:`linestyle`
             If a list, the individual elements are assigned to the elements of the
             collection.
 
@@ -1933,14 +1933,8 @@ def __init__(self,
             The line width of the event lines, in points.
         color : :mpltype:`color` or list of :mpltype:`color`, default: :rc:`lines.color`
             The color of the event lines.
-        linestyle : str or tuple or list thereof, default: 'solid'
-            Valid strings are ['solid', 'dashed', 'dashdot', 'dotted',
-            '-', '--', '-.', ':']. Dash tuples should be of the form::
-
-                (offset, onoffseq),
-
-            where *onoffseq* is an even length tuple of on and off ink
-            in points.
+        linestyle : :mpltype:`linestyle`, default: 'solid'
+            The linestyle of the event lines.
         antialiased : bool or list thereof, default: :rc:`lines.antialiased`
             Whether to use antialiasing for drawing the lines.
         **kwargs

diff --git a/lib/matplotlib/inset.py b/lib/matplotlib/inset.py
@@ -128,38 +128,11 @@ def set_linestyle(self, ls):
 
         Parameters
         ----------
-        ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)
-            Possible values:
+        ls : :mpltype:`linestyle`
+            A named line style (e.g. "dashed", or short "--") or a dash tuple
+            ``(offset, (on_off_seq))``.
 
-            - A string:
-
-              =======================================================  ================
-              linestyle                                                description
-              =======================================================  ================
-              ``'-'`` or ``'solid'``                                   solid line
-              ``'--'`` or ``'dashed'``                                 dashed line
-              ``'-.'`` or ``'dashdot'``                                dash-dotted line
-              ``':'`` or ``'dotted'``                                  dotted line
-              ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``)  draw nothing
-              =======================================================  ================
-
-            - A tuple describing the start position and lengths of dashes and spaces:
-
-                  (offset, onoffseq)
-
-              where
-
-              - *offset* is a float specifying the offset (in points); i.e. how much
-                is the dash pattern shifted.
-              - *onoffseq* is a sequence of on and off ink in points. There can be
-                arbitrary many pairs of on and off values.
-
-              Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts
-              at the beginning of the line. It draws a 10 point long dash,
-              then a 5 point long space, then a 1 point long dash, followed by a 5 point
-              long space, and then the pattern repeats.
-
-            For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`.
+            For a full reference see :doc:`/gallery/lines_bars_and_markers/linestyles`.
         """
         self._shared_setter('linestyle', ls)
 

diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -1165,7 +1165,7 @@ def set_linestyle(self, ls):
 
         Parameters
         ----------
-        ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)
+        ls : :mpltype:`linestyle`
             Possible values:
 
             - A string:

diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -510,38 +510,11 @@ def set_linestyle(self, ls):
 
         Parameters
         ----------
-        ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)
-            Possible values:
+        ls : :mpltype:`linestyle`
+            A named line style (e.g. "dashed", or short "--") or a dash tuple
+            ``(offset, (on_off_seq))``.
 
-            - A string:
-
-              =======================================================  ================
-              linestyle                                                description
-              =======================================================  ================
-              ``'-'`` or ``'solid'``                                   solid line
-              ``'--'`` or ``'dashed'``                                 dashed line
-              ``'-.'`` or ``'dashdot'``                                dash-dotted line
-              ``':'`` or ``'dotted'``                                  dotted line
-              ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``)  draw nothing
-              =======================================================  ================
-
-            - A tuple describing the start position and lengths of dashes and spaces:
-
-                  (offset, onoffseq)
-
-              where
-
-              - *offset* is a float specifying the offset (in points); i.e. how much
-                is the dash pattern shifted.
-              - *onoffseq* is a sequence of on and off ink in points. There can be
-                arbitrary many pairs of on and off values.
-
-              Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts
-              at the beginning of the line. It draws a 10 point long dash,
-              then a 5 point long space, then a 1 point long dash, followed by a 5 point
-              long space, and then the pattern repeats.
-
-            For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`.
+            For a full reference see :doc:`/gallery/lines_bars_and_markers/linestyles`.
         """
         if ls is None:
             ls = "solid"

diff --git a/lib/matplotlib/sphinxext/roles.py b/lib/matplotlib/sphinxext/roles.py
@@ -143,6 +143,7 @@ def _mpltype_role(name, rawtext, text, lineno, inliner, options=None, content=No
     type_to_link_target = {
         'color': 'colors_def',
         'hatch': 'hatch_def',
+        'linestyle': 'linestyle_def',
     }
     if mpltype not in type_to_link_target:
         raise ValueError(f"Unknown mpltype: {mpltype!r}")