matplotlib
diff --git a/‎doc/api/next_api_changes/behavior/28363-TS.rst
Copy file name to clipboard
+6Lines changed: 6 additions & 0 deletions b/‎doc/api/next_api_changes/behavior/28363-TS.rst
Copy file name to clipboard
+6Lines changed: 6 additions & 0 deletions
diff --git a/‎doc/users/next_whats_new/subfigures_change_order.rst
Copy file name to clipboard
+23Lines changed: 23 additions & 0 deletions b/‎doc/users/next_whats_new/subfigures_change_order.rst
Copy file name to clipboard
+23Lines changed: 23 additions & 0 deletions
diff --git a/‎lib/matplotlib/figure.py
Copy file name to clipboardExpand all lines: lib/matplotlib/figure.py
+6-3Lines changed: 6 additions & 3 deletions b/‎lib/matplotlib/figure.py
Copy file name to clipboardExpand all lines: lib/matplotlib/figure.py
+6-3Lines changed: 6 additions & 3 deletions
diff --git a/‎lib/matplotlib/tests/test_figure.py
Copy file name to clipboardExpand all lines: lib/matplotlib/tests/test_figure.py
+8Lines changed: 8 additions & 0 deletions b/‎lib/matplotlib/tests/test_figure.py
Copy file name to clipboardExpand all lines: lib/matplotlib/tests/test_figure.py
+8Lines changed: 8 additions & 0 deletions
@@ -0,0 +1,6 @@
+Subfigures
+~~~~~~~~~~
+
+`.Figure.subfigures` are now added in row-major order to be consistent with
+`.Figure.subplots`.  The return value of `~.Figure.subfigures` is not changed,
+but the order of ``fig.subfigs`` is.
@@ -0,0 +1,23 @@
+Subfigures are now added in row-major order
+-------------------------------------------
+
+``Figure.subfigures`` are now added in row-major order for API consistency.
+
+
+.. plot::
+    :include-source: true
+    :alt: Example of creating 3 by 3 subfigures.
+
+    import matplotlib.pyplot as plt
+
+    fig = plt.figure()
+    subfigs = fig.subfigures(3, 3)
+    x = np.linspace(0, 10, 100)
+
+    for i, sf in enumerate(fig.subfigs):
+        ax = sf.subplots()
+        ax.plot(x, np.sin(x + i), label=f'Subfigure {i+1}')
+        sf.suptitle(f'Subfigure {i+1}')
+        ax.set_xticks([])
+        ax.set_yticks([])
+    plt.show()
@@ -1552,6 +1552,9 @@ def subfigures(self, nrows=1, ncols=1, squeeze=True,
         .. note::
             The *subfigure* concept is new in v3.4, and the API is still provisional.
 
+        .. versionchanged:: 3.10
+            subfigures are now added in row-major order.
+
         Parameters
         ----------
         nrows, ncols : int, default: 1
@@ -1585,9 +1588,9 @@ def subfigures(self, nrows=1, ncols=1, squeeze=True,
                       left=0, right=1, bottom=0, top=1)
 
         sfarr = np.empty((nrows, ncols), dtype=object)
-        for i in range(ncols):
-            for j in range(nrows):
-                sfarr[j, i] = self.add_subfigure(gs[j, i], **kwargs)
+        for i in range(nrows):
+            for j in range(ncols):
+                sfarr[i, j] = self.add_subfigure(gs[i, j], **kwargs)
 
         if self.get_layout_engine() is None and (wspace is not None or
                                                  hspace is not None):
 
@@ -1733,3 +1733,11 @@ def test_warn_colorbar_mismatch():
     subfig3_1.colorbar(im3_2)   # should not warn
     with pytest.warns(UserWarning, match="different Figure"):
         subfig3_1.colorbar(im4_1)
+
+
+def test_subfigure_row_order():
+    # Test that subfigures are drawn in row-major order.
+    fig = plt.figure()
+    sf_arr = fig.subfigures(4, 3)
+    for a, b in zip(sf_arr.ravel(), fig.subfigs):
+        assert a is b