matplotlib · szzhoujiarui-sketch · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1,3 +1,3 @@
 """
 `matplotlib.figure` implements the following classes:

@@ -315,14 +315,14 @@
         ----------
         t : str
             The %(name)s text.
-        x : float, default: %(x0)s
+        x : float, default: :rc:`%(x0)s`
             The x location of the text in figure coordinates.
-        y : float, default: %(y0)s
+        y : float, default: :rc:`%(y0)s`
             The y location of the text in figure coordinates.
-        horizontalalignment, ha : {'center', 'left', 'right'}, default: %(ha)s
+        horizontalalignment, ha : {'center', 'left', 'right'}, default: :rc:`%(ha)s`
             The horizontal alignment of the text relative to (*x*, *y*).
         verticalalignment, va : {'top', 'center', 'bottom', 'baseline'}, \
-default: %(va)s
+default: :rc:`%(va)s`
             The vertical alignment of the text relative to (*x*, *y*).
         fontsize, size : default: :rc:`figure.%(rc)ssize`
             The font size of the text. See `.Text.set_size` for possible
@@ -355,13 +355,19 @@
         elif info['name'] == '_supylabel':
             autopos = x is None
         if x is None:
-            x = info['x0']
+            x = mpl.rcParams[info['x0']] if isinstance(info['x0'], str) else info['x0']
         if y is None:
-            y = info['y0']
+            y = mpl.rcParams[info['y0']] if isinstance(info['y0'], str) else info['y0']
 
         kwargs = cbook.normalize_kwargs(kwargs, Text)
-        kwargs.setdefault('horizontalalignment', info['ha'])
-        kwargs.setdefault('verticalalignment', info['va'])
+        kwargs.setdefault('horizontalalignment',
+                          mpl.rcParams[info['ha']]
+                          if info['ha'] in mpl.rcParams
+                          else info['ha'])
+        kwargs.setdefault('verticalalignment',
+                          mpl.rcParams[info['va']]
+                          if info['va'] in mpl.rcParams
+                          else info['va'])
         kwargs.setdefault('rotation', info['rotation'])
 
         if 'fontproperties' not in kwargs:
@@ -387,13 +393,18 @@
         self.texts.remove(label)
         setattr(self, name, None)
 
-    @_docstring.Substitution(x0=0.5, y0=0.98, name='super title', ha='center',
-                             va='top', rc='title')
+    @_docstring.Substitution(x0='figure.title_x', y0='figure.title_y',
+                             name='super title',
+                             ha='figure.title_horizontalalignment',
+                             va='figure.title_verticalalignment', rc='title')
     @_docstring.copy(_suplabels)
     def suptitle(self, t, **kwargs):
         # docstring from _suplabels...
-        info = {'name': '_suptitle', 'x0': 0.5, 'y0': 0.98,
-                'ha': 'center', 'va': 'top', 'rotation': 0,
+        info = {'name': '_suptitle',
+                'x0': 'figure.title_x', 'y0': 'figure.title_y',
+                'ha': 'figure.title_horizontalalignment',
+                'va': 'figure.title_verticalalignment',
+                'rotation': 0,
                 'size': 'figure.titlesize', 'weight': 'figure.titleweight'}
         return self._suplabels(t, info, **kwargs)
 

diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -601,6 +601,10 @@
 ## See https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure
 #figure.titlesize:   large     # size of the figure title (``Figure.suptitle()``)
 #figure.titleweight: normal    # weight of the figure title
+#figure.title_x:     0.5      # x location of the figure title in figure coordinates
+#figure.title_y:     0.98     # y location of the figure title in figure coordinates
+#figure.title_horizontalalignment: center  # horizontal alignment of the figure title
+#figure.title_verticalalignment: top       # vertical alignment of the figure title
 #figure.labelsize:   large     # size of the figure label (``Figure.sup[x|y]label()``)
 #figure.labelweight: normal    # weight of the figure label
 #figure.figsize:     6.4, 4.8  # figure size in inches

diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1349,6 +1349,10 @@ def _convert_validator_spec(key, conv):
     # figure title
     "figure.titlesize":   validate_fontsize,
     "figure.titleweight": validate_fontweight,
+    "figure.title_x":    validate_float,
+    "figure.title_y":    validate_float,
+    "figure.title_horizontalalignment": ["center", "left", "right"],
+    "figure.title_verticalalignment": ["top", "center", "bottom", "baseline"],
 
     # figure labels
     "figure.labelsize":   validate_fontsize,
@@ -2769,6 +2773,30 @@ class _Subsection:
         validator=validate_fontweight,
         description="weight of the figure title"
     ),
+    _Param(
+        "figure.title_x",
+        default=0.5,
+        validator=validate_float,
+        description="x location of the figure title in figure coordinates"
+    ),
+    _Param(
+        "figure.title_y",
+        default=0.98,
+        validator=validate_float,
+        description="y location of the figure title in figure coordinates"
+    ),
+    _Param(
+        "figure.title_horizontalalignment",
+        default="center",
+        validator=["center", "left", "right"],
+        description="horizontal alignment of the figure title"
+    ),
+    _Param(
+        "figure.title_verticalalignment",
+        default="top",
+        validator=["top", "center", "bottom", "baseline"],
+        description="vertical alignment of the figure title"
+    ),
     _Param(
         "figure.labelsize",
         default="large",

diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -1900,3 +1900,38 @@ def test_figsize_both_none():
 def test_figsize_invalid_unit():
     with pytest.raises(ValueError, match="Invalid unit 'um'"):
         plt.figure(figsize=(6, 4, "um"))
+
+
+
+def test_suptitle_rcparams():
+    """Test that suptitle respects figure.title_* rcParams."""
+    rc = {
+        'figure.title_x': 0.3,
+        'figure.title_y': 0.9,
+        'figure.title_horizontalalignment': 'left',
+        'figure.title_verticalalignment': 'bottom',
+    }
+    with plt.rc_context(rc=rc):
+        fig = plt.figure()
+        t = fig.suptitle("test")
+        assert t.get_position() == (0.3, 0.9)
+        assert t.get_horizontalalignment() == 'left'
+        assert t.get_verticalalignment() == 'bottom'
+
+
+def test_suptitle_rcparams_override():
+    """Test that explicit kwargs override rcParams for suptitle."""
+    rc = {
+        'figure.title_x': 0.3,
+        'figure.title_y': 0.9,
+        'figure.title_horizontalalignment': 'left',
+        'figure.title_verticalalignment': 'bottom',
+    }
+    with plt.rc_context(rc=rc):
+        fig = plt.figure()
+        t = fig.suptitle("test", x=0.7, y=0.5,
+                         horizontalalignment='right',
+                         verticalalignment='top')
+        assert t.get_position() == (0.7, 0.5)
+        assert t.get_horizontalalignment() == 'right'
+        assert t.get_verticalalignment() == 'top'
diff --git a/lib/matplotlib/typing.py b/lib/matplotlib/typing.py
@@ -321,6 +321,10 @@
     "figure.subplot.wspace",
     "figure.titlesize",
     "figure.titleweight",
+    "figure.title_horizontalalignment",
+    "figure.title_verticalalignment",
+    "figure.title_x",
+    "figure.title_y",
     "font.cursive",
     "font.enable_last_resort",
     "font.family",