streamlit 1.49.1__py3-none-any.whl → 1.51.0__py3-none-any.whl

streamlit/elements/vega_charts.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 import json
 import re
+import threading
 from contextlib import nullcontext
 from dataclasses import dataclass
 from typing import (
@@ -25,15 +26,20 @@ from typing import (
     Any,
     Final,
     Literal,
+    TypeAlias,
     TypedDict,
     Union,
     cast,
     overload,
 )
 
-from typing_extensions import Required, TypeAlias
+from typing_extensions import Required
 
 from streamlit import dataframe_util, type_util
+from streamlit.deprecation_util import (
+    make_deprecated_name_warning,
+    show_deprecation_warning,
+)
 from streamlit.elements.lib import dicttools
 from streamlit.elements.lib.built_in_chart_utils import (
     AddRowsMetadata,
@@ -43,6 +49,13 @@ from streamlit.elements.lib.built_in_chart_utils import (
     maybe_raise_stack_warning,
 )
 from streamlit.elements.lib.form_utils import current_form_id
+from streamlit.elements.lib.layout_utils import (
+    Height,
+    LayoutConfig,
+    Width,
+    validate_height,
+    validate_width,
+)
 from streamlit.elements.lib.policies import check_widget_policies
 from streamlit.elements.lib.utils import Key, compute_and_register_element_id, to_key
 from streamlit.errors import StreamlitAPIException
@@ -104,6 +117,8 @@ AltairChart: TypeAlias = Union[
     "alt.VConcatChart",
 ]
 
+_altair_globals_lock = threading.Lock()
+
 
 class VegaLiteState(TypedDict, total=False):
     """
@@ -321,7 +336,7 @@ def _marshall_chart_data(
             dataset = proto.datasets.add()
             dataset.name = str(dataset_name)
             dataset.has_name = True
-            # The ID transformer (id_transform function registered before conversion to dict)
+            # The ID transformer (_to_arrow_dataset function registered before conversion to dict)
             # already serializes the data into Arrow IPC format (bytes) when the Altair object
             # gets converted into the vega-lite spec dict.
             # If its already in bytes, we don't need to serialize it here again.
@@ -362,41 +377,46 @@ def _convert_altair_to_vega_lite_spec(
     """Convert an Altair chart object to a Vega-Lite chart spec."""
     import altair as alt
 
+    # alt.themes was deprecated in Altair 5.5.0 in favor of alt.theme
+    if type_util.is_altair_version_less_than("5.5.0"):
+        alt_theme = alt.themes  # ty: ignore[unresolved-attribute]
+    else:
+        alt_theme = alt.theme
+
+    # This is where we'll store Arrow-serialized versions of the chart data.
+    # This happens in _to_arrow_dataset().
+    datasets: dict[str, Any] = {}
+
     # Normally altair_chart.to_dict() would transform the dataframe used by the
     # chart into an array of dictionaries. To avoid that, we install a
     # transformer that replaces datasets with a reference by the object id of
     # the dataframe. We then fill in the dataset manually later on.
+    #
+    # Note: it's OK to re-register this every time we run this function since
+    # transformers are stored in a dict. So there's no duplication.
+    #
+    # type: ignore[arg-type,attr-defined,unused-ignore]
+    alt.data_transformers.register("to_arrow_dataset", _to_arrow_dataset)
+
+    # Settings like alt.theme.enable and alt.data_transformers.enable are global to all
+    # threads. So this lock makes sure that whatever we set those to only apply to the
+    # current thread.
+    with _altair_globals_lock:
+        # The default altair theme has some width/height defaults defined
+        # which are not useful for Streamlit. Therefore, we change the theme to
+        # "none" to avoid those defaults.
+        theme_context = (
+            alt_theme.enable("none") if alt_theme.active == "default" else nullcontext()
+        )
 
-    datasets = {}
-
-    def id_transform(data: Any) -> dict[str, str]:
-        """Altair data transformer that serializes the data,
-        creates a stable name based on the hash of the data,
-        stores the bytes into the datasets mapping and
-        returns this name to have it be used in Altair.
-        """
-        # Already serialize the data to be able to create a stable
-        # dataset name:
-        data_bytes = dataframe_util.convert_anything_to_arrow_bytes(data)
-        # Use the md5 hash of the data as the name:
-        name = calc_md5(str(data_bytes))
-
-        datasets[name] = data_bytes
-        return {"name": name}
-
-    alt.data_transformers.register("id", id_transform)  # type: ignore[arg-type,attr-defined,unused-ignore]
-
-    # alt.themes was deprecated in Altair 5.5.0 in favor of alt.theme
-    alt_theme = (
-        alt.themes if type_util.is_altair_version_less_than("5.5.0") else alt.theme  # ty: ignore[unresolved-attribute]
-    )
+        data_transformer = alt.data_transformers.enable(
+            "to_arrow_dataset", datasets=datasets
+        )
 
-    # The default altair theme has some width/height defaults defined
-    # which are not useful for Streamlit. Therefore, we change the theme to
-    # "none" to avoid those defaults.
-    with alt_theme.enable("none") if alt_theme.active == "default" else nullcontext():  # ty: ignore
-        with alt.data_transformers.enable("id"):  # type: ignore[attr-defined,unused-ignore]
-            chart_dict = altair_chart.to_dict()
+        with theme_context:  # ty: ignore[invalid-context-manager]
+            # type: ignore[attr-defined,unused-ignore]
+            with data_transformer:  # ty: ignore[invalid-context-manager]
+                chart_dict = altair_chart.to_dict()
 
     # Put datasets back into the chart dict:
     chart_dict["datasets"] = datasets
@@ -596,9 +616,9 @@ class VegaChartsMixin:
         x_label: str | None = None,
         y_label: str | None = None,
         color: str | Color | list[Color] | None = None,
-        width: int | None = None,
-        height: int | None = None,
-        use_container_width: bool = True,
+        width: Width = "stretch",
+        height: Height = "content",
+        use_container_width: bool | None = None,
     ) -> DeltaGenerator:
         """Display a line chart.
 
@@ -607,9 +627,6 @@ class VegaChartsMixin:
         the chart's Altair spec. As a result this is easier to use for many
         "just plot this" scenarios, while being less customizable.
 
-        If ``st.line_chart`` does not guess the data specification
-        correctly, try specifying your desired chart using ``st.altair_chart``.
-
         Parameters
         ----------
         data : Anything supported by st.dataframe
@@ -680,27 +697,46 @@ class VegaChartsMixin:
             You can set the default colors in the ``theme.chartCategoryColors``
             configuration option.
 
-        width : int or None
-            Desired width of the chart expressed in pixels. If ``width`` is
-            ``None`` (default), Streamlit sets the width of the chart to fit
-            its contents according to the plotting library, up to the width of
-            the parent container. If ``width`` is greater than the width of the
-            parent container, Streamlit sets the chart width to match the width
-            of the parent container.
+        width : "stretch", "content", or int
+            The width of the chart element. This can be one of the following:
 
-            To use ``width``, you must set ``use_container_width=False``.
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
+        height : "content", "stretch", or int
+            The height of the chart element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
 
-        height : int or None
-            Desired height of the chart expressed in pixels. If ``height`` is
-            ``None`` (default), Streamlit sets the height of the chart to fit
-            its contents according to the plotting library.
+        use_container_width : bool or None
+            Whether to override the chart's native width with the width of
+            the parent container. This can be one of the following:
 
-        use_container_width : bool
-            Whether to override ``width`` with the width of the parent
-            container. If ``use_container_width`` is ``True`` (default),
-            Streamlit sets the width of the chart to match the width of the
-            parent container. If ``use_container_width`` is ``False``,
-            Streamlit sets the chart's width according to ``width``.
+            - ``None`` (default): Streamlit will use the chart's default behavior.
+            - ``True``: Streamlit sets the width of the chart to match the
+              width of the parent container.
+            - ``False``: Streamlit sets the width of the chart to fit its
+              contents according to the plotting library, up to the width of
+              the parent container.
+
+            .. deprecated::
+               ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
 
         Examples
         --------
@@ -777,7 +813,6 @@ class VegaChartsMixin:
            height: 440px
 
         """
-
         chart, add_rows_metadata = generate_chart(
             chart_type=ChartType.LINE,
             data=data,
@@ -789,8 +824,9 @@ class VegaChartsMixin:
             size_from_user=None,
             width=width,
             height=height,
-            use_container_width=use_container_width,
+            use_container_width=(width == "stretch"),
         )
+
         return cast(
             "DeltaGenerator",
             self._altair_chart(
@@ -798,6 +834,8 @@ class VegaChartsMixin:
                 use_container_width=use_container_width,
                 theme="streamlit",
                 add_rows_metadata=add_rows_metadata,
+                width=width,
+                height=height,
             ),
         )
 
@@ -812,9 +850,9 @@ class VegaChartsMixin:
         y_label: str | None = None,
         color: str | Color | list[Color] | None = None,
         stack: bool | ChartStackType | None = None,
-        width: int | None = None,
-        height: int | None = None,
-        use_container_width: bool = True,
+        width: Width = "stretch",
+        height: Height = "content",
+        use_container_width: bool | None = None,
     ) -> DeltaGenerator:
         """Display an area chart.
 
@@ -823,9 +861,6 @@ class VegaChartsMixin:
         the chart's Altair spec. As a result this is easier to use for many
         "just plot this" scenarios, while being less customizable.
 
-        If ``st.area_chart`` does not guess the data specification
-        correctly, try specifying your desired chart using ``st.altair_chart``.
-
         Parameters
         ----------
         data : Anything supported by st.dataframe
@@ -908,27 +943,46 @@ class VegaChartsMixin:
             - ``"center"``: The areas are stacked and shifted to center their
               baseline, which creates a steamgraph.
 
-        width : int or None
-            Desired width of the chart expressed in pixels. If ``width`` is
-            ``None`` (default), Streamlit sets the width of the chart to fit
-            its contents according to the plotting library, up to the width of
-            the parent container. If ``width`` is greater than the width of the
-            parent container, Streamlit sets the chart width to match the width
-            of the parent container.
+        width : "stretch", "content", or int
+            The width of the chart element. This can be one of the following:
 
-            To use ``width``, you must set ``use_container_width=False``.
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
+        height : "stretch", "content", or int
+            The height of the chart element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
 
-        height : int or None
-            Desired height of the chart expressed in pixels. If ``height`` is
-            ``None`` (default), Streamlit sets the height of the chart to fit
-            its contents according to the plotting library.
+        use_container_width : bool or None
+            Whether to override the chart's native width with the width of
+            the parent container. This can be one of the following:
 
-        use_container_width : bool
-            Whether to override ``width`` with the width of the parent
-            container. If ``use_container_width`` is ``True`` (default),
-            Streamlit sets the width of the chart to match the width of the
-            parent container. If ``use_container_width`` is ``False``,
-            Streamlit sets the chart's width according to ``width``.
+            - ``None`` (default): Streamlit will use the chart's default behavior.
+            - ``True``: Streamlit sets the width of the chart to match the
+              width of the parent container.
+            - ``False``: Streamlit sets the width of the chart to fit its
+              contents according to the plotting library, up to the width of
+              the parent container.
+
+            .. deprecated::
+               ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
 
         Examples
         --------
@@ -1029,7 +1083,6 @@ class VegaChartsMixin:
            height: 440px
 
         """
-
         # Check that the stack parameter is valid, raise more informative error message if not
         maybe_raise_stack_warning(
             stack,
@@ -1059,7 +1112,7 @@ class VegaChartsMixin:
             width=width,
             height=height,
             stack=stack,
-            use_container_width=use_container_width,
+            use_container_width=(width == "stretch"),
         )
         return cast(
             "DeltaGenerator",
@@ -1068,6 +1121,8 @@ class VegaChartsMixin:
                 use_container_width=use_container_width,
                 theme="streamlit",
                 add_rows_metadata=add_rows_metadata,
+                width=width,
+                height=height,
             ),
         )
 
@@ -1082,10 +1137,11 @@ class VegaChartsMixin:
         y_label: str | None = None,
         color: str | Color | list[Color] | None = None,
         horizontal: bool = False,
+        sort: bool | str = True,
         stack: bool | ChartStackType | None = None,
-        width: int | None = None,
-        height: int | None = None,
-        use_container_width: bool = True,
+        width: Width = "stretch",
+        height: Height = "content",
+        use_container_width: bool | None = None,
     ) -> DeltaGenerator:
         """Display a bar chart.
 
@@ -1094,9 +1150,6 @@ class VegaChartsMixin:
         the chart's Altair spec. As a result this is easier to use for many
         "just plot this" scenarios, while being less customizable.
 
-        If ``st.bar_chart`` does not guess the data specification
-        correctly, try specifying your desired chart using ``st.altair_chart``.
-
         Parameters
         ----------
         data : Anything supported by st.dataframe
@@ -1173,6 +1226,19 @@ class VegaChartsMixin:
             Streamlit swaps the x-axis and y-axis and the bars display
             horizontally.
 
+        sort : bool or str
+            How to sort the bars. This can be one of the following:
+
+            - ``True`` (default): The bars are sorted automatically along the
+              independent/categorical axis with Altair's default sorting. This
+              also correctly sorts ordered categorical columns
+              (``pd.Categorical``).
+            - ``False``: The bars are shown in data order without sorting.
+            - The name of a column (e.g. ``"col1"``): The bars are sorted by
+              that column in ascending order.
+            - The name of a column with a minus-sign prefix (e.g. ``"-col1"``):
+              The bars are sorted by that column in descending order.
+
         stack : bool, "normalize", "center", "layered", or None
             Whether to stack the bars. If this is ``None`` (default),
             Streamlit uses Vega's default. Other values can be as follows:
@@ -1186,27 +1252,46 @@ class VegaChartsMixin:
             - ``"center"``: The bars are stacked and shifted to center the
               total height around an axis.
 
-        width : int or None
-            Desired width of the chart expressed in pixels. If ``width`` is
-            ``None`` (default), Streamlit sets the width of the chart to fit
-            its contents according to the plotting library, up to the width of
-            the parent container. If ``width`` is greater than the width of the
-            parent container, Streamlit sets the chart width to match the width
-            of the parent container.
+        width : "stretch", "content", or int
+            The width of the chart element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
+        height : "stretch", "content", or int
+            The height of the chart element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
 
-            To use ``width``, you must set ``use_container_width=False``.
+        use_container_width : bool or None
+            Whether to override the chart's native width with the width of
+            the parent container. This can be one of the following:
 
-        height : int or None
-            Desired height of the chart expressed in pixels. If ``height`` is
-            ``None`` (default), Streamlit sets the height of the chart to fit
-            its contents according to the plotting library.
+            - ``None`` (default): Streamlit will use the chart's default behavior.
+            - ``True``: Streamlit sets the width of the chart to match the
+              width of the parent container.
+            - ``False``: Streamlit sets the width of the chart to fit its
+              contents according to the plotting library, up to the width of
+              the parent container.
 
-        use_container_width : bool
-            Whether to override ``width`` with the width of the parent
-            container. If ``use_container_width`` is ``True`` (default),
-            Streamlit sets the width of the chart to match the width of the
-            parent container. If ``use_container_width`` is ``False``,
-            Streamlit sets the chart's width according to ``width``.
+            .. deprecated::
+               ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
 
         Examples
         --------
@@ -1324,7 +1409,6 @@ class VegaChartsMixin:
            height: 440px
 
         """
-
         # Check that the stack parameter is valid, raise more informative error message if not
         maybe_raise_stack_warning(
             stack,
@@ -1357,6 +1441,7 @@ class VegaChartsMixin:
             use_container_width=use_container_width,
             stack=stack,
             horizontal=horizontal,
+            sort_from_user=sort,
         )
         return cast(
             "DeltaGenerator",
@@ -1365,6 +1450,8 @@ class VegaChartsMixin:
                 use_container_width=use_container_width,
                 theme="streamlit",
                 add_rows_metadata=add_rows_metadata,
+                width=width,
+                height=height,
             ),
         )
 
@@ -1379,9 +1466,9 @@ class VegaChartsMixin:
         y_label: str | None = None,
         color: str | Color | list[Color] | None = None,
         size: str | float | int | None = None,
-        width: int | None = None,
-        height: int | None = None,
-        use_container_width: bool = True,
+        width: Width = "stretch",
+        height: Height = "content",
+        use_container_width: bool | None = None,
     ) -> DeltaGenerator:
         """Display a scatterplot chart.
 
@@ -1390,9 +1477,6 @@ class VegaChartsMixin:
         the chart's Altair spec. As a result this is easier to use for many
         "just plot this" scenarios, while being less customizable.
 
-        If ``st.scatter_chart`` does not guess the data specification correctly,
-        try specifying your desired chart using ``st.altair_chart``.
-
         Parameters
         ----------
         data : Anything supported by st.dataframe
@@ -1469,27 +1553,46 @@ class VegaChartsMixin:
             - The name of the column to use for the size. This allows each
               datapoint to be represented by a circle of a different size.
 
-        width : int or None
-            Desired width of the chart expressed in pixels. If ``width`` is
-            ``None`` (default), Streamlit sets the width of the chart to fit
-            its contents according to the plotting library, up to the width of
-            the parent container. If ``width`` is greater than the width of the
-            parent container, Streamlit sets the chart width to match the width
-            of the parent container.
+        width : "stretch", "content", or int
+            The width of the chart element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
+        height : "stretch", "content", or int
+            The height of the chart element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
 
-            To use ``width``, you must set ``use_container_width=False``.
+        use_container_width : bool or None
+            Whether to override the chart's native width with the width of
+            the parent container. This can be one of the following:
 
-        height : int or None
-            Desired height of the chart expressed in pixels. If ``height`` is
-            ``None`` (default), Streamlit sets the height of the chart to fit
-            its contents according to the plotting library.
+            - ``None`` (default): Streamlit will use the chart's default behavior.
+            - ``True``: Streamlit sets the width of the chart to match the
+              width of the parent container.
+            - ``False``: Streamlit sets the width of the chart to fit its
+              contents according to the plotting library, up to the width of
+              the parent container.
 
-        use_container_width : bool
-            Whether to override ``width`` with the width of the parent
-            container. If ``use_container_width`` is ``True`` (default),
-            Streamlit sets the width of the chart to match the width of the
-            parent container. If ``use_container_width`` is ``False``,
-            Streamlit sets the chart's width according to ``width``.
+            .. deprecated::
+               ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
 
         Examples
         --------
@@ -1574,7 +1677,6 @@ class VegaChartsMixin:
            height: 440px
 
         """
-
         chart, add_rows_metadata = generate_chart(
             chart_type=ChartType.SCATTER,
             data=data,
@@ -1586,7 +1688,7 @@ class VegaChartsMixin:
             size_from_user=size,
             width=width,
             height=height,
-            use_container_width=use_container_width,
+            use_container_width=(width == "stretch"),
         )
         return cast(
             "DeltaGenerator",
@@ -1595,6 +1697,8 @@ class VegaChartsMixin:
                 use_container_width=use_container_width,
                 theme="streamlit",
                 add_rows_metadata=add_rows_metadata,
+                width=width,
+                height=height,
             ),
         )
 
@@ -1604,6 +1708,8 @@ class VegaChartsMixin:
         self,
         altair_chart: AltairChart,
         *,
+        width: Width | None = None,
+        height: Height = "content",
         use_container_width: bool | None = None,
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
@@ -1617,6 +1723,8 @@ class VegaChartsMixin:
         self,
         altair_chart: AltairChart,
         *,
+        width: Width | None = None,
+        height: Height = "content",
         use_container_width: bool | None = None,
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
@@ -1629,6 +1737,8 @@ class VegaChartsMixin:
         self,
         altair_chart: AltairChart,
         *,
+        width: Width | None = None,
+        height: Height = "content",
         use_container_width: bool | None = None,
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
@@ -1648,6 +1758,39 @@ class VegaChartsMixin:
             https://altair-viz.github.io/gallery/ for examples of graph
             descriptions.
 
+        width : "stretch", "content", int, or None
+            The width of the chart element. This can be one of the following:
+
+            - ``"stretch"``: The width of the element matches the width of the
+              parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+            - ``None`` (default): Streamlit uses ``"stretch"`` for most charts,
+              and uses ``"content"`` for the following multi-view charts:
+
+                - Facet charts: the spec contains ``"facet"`` or encodings for
+                  ``"row"``, ``"column"``, or ``"facet"``.
+                - Horizontal concatenation charts: the spec contains
+                  ``"hconcat"``.
+                - Repeat charts: the spec contains ``"repeat"``.
+
+        height : "content", "stretch", or int
+            The height of the chart element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
+
         use_container_width : bool or None
             Whether to override the chart's native width with the width of
             the parent container. This can be one of the following:
@@ -1662,6 +1805,11 @@ class VegaChartsMixin:
               contents according to the plotting library, up to the width of
               the parent container.
 
+            .. deprecated::
+               ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
+
         theme : "streamlit" or None
             The theme of the chart. If ``theme`` is ``"streamlit"`` (default),
             Streamlit uses its own design default. If ``theme`` is ``None``,
@@ -1754,6 +1902,8 @@ class VegaChartsMixin:
         """
         return self._altair_chart(
             altair_chart=altair_chart,
+            width=width,
+            height=height,
             use_container_width=use_container_width,
             theme=theme,
             key=key,
@@ -1768,6 +1918,8 @@ class VegaChartsMixin:
         data: Data = None,
         spec: VegaLiteSpec | None = None,
         *,
+        width: Width | None = None,
+        height: Height = "content",
         use_container_width: bool | None = None,
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
@@ -1783,6 +1935,8 @@ class VegaChartsMixin:
         data: Data = None,
         spec: VegaLiteSpec | None = None,
         *,
+        width: Width | None = None,
+        height: Height = "content",
         use_container_width: bool | None = None,
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
@@ -1797,6 +1951,8 @@ class VegaChartsMixin:
         data: Data = None,
         spec: VegaLiteSpec | None = None,
         *,
+        width: Width | None = None,
+        height: Height = "content",
         use_container_width: bool | None = None,
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
@@ -1821,6 +1977,39 @@ class VegaChartsMixin:
             to both ``data`` and ``spec``. See
             https://vega.github.io/vega-lite/docs/ for more info.
 
+        width : "stretch", "content", int, or None
+            The width of the chart element. This can be one of the following:
+
+            - ``"stretch"``: The width of the element matches the width of the
+              parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+            - ``None`` (default): Streamlit uses ``"stretch"`` for most charts,
+              and uses ``"content"`` for the following multi-view charts:
+
+                - Facet charts: the spec contains ``"facet"`` or encodings for
+                  ``"row"``, ``"column"``, or ``"facet"``.
+                - Horizontal concatenation charts: the spec contains
+                  ``"hconcat"``.
+                - Repeat charts: the spec contains ``"repeat"``.
+
+        height : "content", "stretch", or int
+            The height of the chart element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
+
         use_container_width : bool or None
             Whether to override the chart's native width with the width of
             the parent container. This can be one of the following:
@@ -1835,6 +2024,11 @@ class VegaChartsMixin:
               contents according to the plotting library, up to the width of
               the parent container.
 
+            .. deprecated::
+               ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
+
         theme : "streamlit" or None
             The theme of the chart. If ``theme`` is ``"streamlit"`` (default),
             Streamlit uses its own design default. If ``theme`` is ``None``,
@@ -1944,6 +2138,8 @@ class VegaChartsMixin:
             key=key,
             on_select=on_select,
             selection_mode=selection_mode,
+            width=width,
+            height=height,
             **kwargs,
         )
 
@@ -1956,6 +2152,8 @@ class VegaChartsMixin:
         on_select: Literal["rerun", "ignore"] | WidgetCallback = "ignore",
         selection_mode: str | Iterable[str] | None = None,
         add_rows_metadata: AddRowsMetadata | None = None,
+        width: Width | None = None,
+        height: Height = "content",
     ) -> DeltaGenerator | VegaLiteState:
         """Internal method to enqueue a vega-lite chart element based on an Altair chart.
 
@@ -1980,6 +2178,8 @@ class VegaChartsMixin:
             on_select=on_select,
             selection_mode=selection_mode,
             add_rows_metadata=add_rows_metadata,
+            width=width,
+            height=height,
         )
 
     def _vega_lite_chart(
@@ -1992,13 +2192,14 @@ class VegaChartsMixin:
         on_select: Literal["rerun", "ignore"] | WidgetCallback = "ignore",
         selection_mode: str | Iterable[str] | None = None,
         add_rows_metadata: AddRowsMetadata | None = None,
+        width: Width | None = None,
+        height: Height = "content",
         **kwargs: Any,
     ) -> DeltaGenerator | VegaLiteState:
         """Internal method to enqueue a vega-lite chart element based on a vega-lite spec.
 
         See the `vega_lite_chart` method docstring for more information.
         """
-
         if theme not in ["streamlit", None]:
             raise StreamlitAPIException(
                 f'You set theme="{theme}" while Streamlit charts only support '
@@ -2037,30 +2238,64 @@ class VegaChartsMixin:
         if spec is None:
             spec = {}
 
-        # Set the default value for `use_container_width`.
-        if use_container_width is None:
+        # Set the default value for width. Altair and Vega charts have different defaults depending on the chart type,
+        # so they don't default the value in the function signature and width could be None here.
+        if use_container_width is None and width is None:
             # Some multi-view charts (facet, horizontal concatenation, and repeat;
             # see https://altair-viz.github.io/user_guide/compound_charts.html)
-            # don't work well with `use_container_width=True`, so we disable it for
+            # don't work well with `width=stretch`, so we disable it for
             # those charts (see https://github.com/streamlit/streamlit/issues/9091).
             # All other charts (including vertical concatenation) default to
-            # `use_container_width=True`.
+            # `width=stretch` unless width is provided.
             is_facet_chart = "facet" in spec or (
                 "encoding" in spec
                 and (any(x in spec["encoding"] for x in ["row", "column", "facet"]))
             )
-            use_container_width = not (
-                is_facet_chart or "hconcat" in spec or "repeat" in spec
+            width = (
+                "stretch"
+                if not (is_facet_chart or "hconcat" in spec or "repeat" in spec)
+                else "content"
+            )
+
+        if use_container_width is not None:
+            show_deprecation_warning(
+                make_deprecated_name_warning(
+                    "use_container_width",
+                    "width",
+                    "2025-12-31",
+                    "For `use_container_width=True`, use `width='stretch'`. "
+                    "For `use_container_width=False`, use `width='content'` or specify an integer width.",
+                    include_st_prefix=False,
+                ),
+                show_in_browser=False,
             )
+            if use_container_width:
+                width = "stretch"
+            elif not isinstance(width, int):
+                # No specific width provided, use content width
+                width = "content"
+                # Otherwise keep the integer width - user explicitly set both use_container_width=False and width=int
+
+        if width is not None:
+            validate_width(width, allow_content=True)
+        validate_height(height, allow_content=True)
 
         vega_lite_proto = ArrowVegaLiteChartProto()
 
-        spec = _prepare_vega_lite_spec(spec, use_container_width, **kwargs)
+        use_container_width_for_spec = (
+            use_container_width
+            if use_container_width is not None
+            else width == "stretch"
+        )
+
+        spec = _prepare_vega_lite_spec(spec, use_container_width_for_spec, **kwargs)
         _marshall_chart_data(vega_lite_proto, spec, data)
 
         # Prevent the spec from changing across reruns:
         vega_lite_proto.spec = _stabilize_vega_json_spec(json.dumps(spec))
-        vega_lite_proto.use_container_width = use_container_width
+
+        if use_container_width is not None:
+            vega_lite_proto.use_container_width = use_container_width
         vega_lite_proto.theme = theme or ""
 
         if is_selection_activated:
@@ -2079,6 +2314,7 @@ class VegaChartsMixin:
             vega_lite_proto.id = compute_and_register_element_id(
                 "arrow_vega_lite_chart",
                 user_key=key,
+                key_as_main_identity=False,
                 dg=self.dg,
                 vega_lite_spec=vega_lite_proto.spec,
                 # The data is either in vega_lite_proto.data.data
@@ -2103,21 +2339,42 @@ class VegaChartsMixin:
                 value_type="string_value",
             )
 
+            layout_config = LayoutConfig(width=width, height=height)
             self.dg._enqueue(
                 "arrow_vega_lite_chart",
                 vega_lite_proto,
                 add_rows_metadata=add_rows_metadata,
+                layout_config=layout_config,
             )
             return widget_state.value
+
         # If its not used with selections activated, just return
         # the delta generator related to this element.
+        layout_config = LayoutConfig(width=width, height=height)
         return self.dg._enqueue(
             "arrow_vega_lite_chart",
             vega_lite_proto,
             add_rows_metadata=add_rows_metadata,
+            layout_config=layout_config,
         )
 
     @property
     def dg(self) -> DeltaGenerator:
         """Get our DeltaGenerator."""
         return cast("DeltaGenerator", self)
+
+
+def _to_arrow_dataset(data: Any, datasets: dict[str, Any]) -> dict[str, str]:
+    """Altair data transformer that serializes the data,
+    creates a stable name based on the hash of the data,
+    stores the bytes into the datasets mapping and
+    returns this name to have it be used in Altair.
+    """
+    # Already serialize the data to be able to create a stable
+    # dataset name:
+    data_bytes = dataframe_util.convert_anything_to_arrow_bytes(data)
+    # Use the md5 hash of the data as the name:
+    name = calc_md5(str(data_bytes))
+
+    datasets[name] = data_bytes
+    return {"name": name}