Zorder DemoΒΆ

The drawing order of artists is determined by their zorder attribute, which is a floating point number. Artists with higher zorder are drawn on top. You can change the order for individual artists by setting their zorder. The default value depends on the type of the Artist:

Artist Z-order
Images (AxesImage, FigureImage, BboxImage) 0
Patch, PatchCollection 1
Line2D, LineCollection (including minor ticks, grid lines) 2
Major ticks 2.01
Text (including axes labels and titles) 3
Legend 5

Any call to a plotting method can set a value for the zorder of that particular item explicitly.


set_axisbelow and rcParams["axes.axisbelow"] (default: 'line') can further modify the zorder of ticks and grid lines.

import matplotlib.pyplot as plt
import numpy as np

r = np.linspace(0.3, 1, 30)
theta = np.linspace(0, 4*np.pi, 30)
x = r * np.sin(theta)
y = r * np.cos(theta)

The following example contains a Line2D created by plot() and the dots (a PatchCollection) created by scatter(). Hence, by default the dots are below the line (first subplot). In the second subplot, the zorder is set explicitly to move the dots on top of the line.

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6, 3.2))

ax1.plot(x, y, 'C3', lw=3)
ax1.scatter(x, y, s=120)
ax1.set_title('Lines on top of dots')

ax2.plot(x, y, 'C3', lw=3)
ax2.scatter(x, y, s=120, zorder=2.5)  # move dots on top of line
ax2.set_title('Dots on top of lines')

Lines on top of dots, Dots on top of lines

Many functions that create a visible object accepts a zorder parameter. Alternatively, you can call set_order() on the created object later.

x = np.linspace(0, 7.5, 100)
plt.rcParams['lines.linewidth'] = 5
plt.plot(x, np.sin(x), label='zorder=2', zorder=2)  # bottom
plt.plot(x, np.sin(x+0.5), label='zorder=3',  zorder=3)
plt.axhline(0, label='zorder=2.5', color='lightgrey', zorder=2.5)
plt.title('Custom order of elements')
l = plt.legend(loc='upper right')
l.set_zorder(2.5)  # legend between blue and orange line
Custom order of elements

Keywords: matplotlib code example, codex, python plot, pyplot Gallery generated by Sphinx-Gallery