Support configuring the `format` in `st.metric` #13193

lukasmasuch · 2025-12-03T09:02:53Z

Describe your changes

Adds support for configuring a format applied to the value and delta on client-side. This supports the same formats that are supported in NumberColumn and ProgressColumn.

GitHub Issue Link (if applicable)

Closes Shorten numbers in st.metric #12229
Related to format_func for st.metric #6951

Testing Plan

Added unit and e2e tests.

Contribution License Agreement

By submitting this pull request you agree that all contributions to this project are made under the Apache 2.0 license.

Note

Adds a format option to st.metric and applies client-side number formatting for value and delta, with shared formatting utilities and tests.

Metric API:
- Add format parameter to st.metric (Python) and Metric proto (format field) to control value/delta formatting.
- Update docsstring; keep existing behavior for non-numeric strings.
Frontend (Metric):
- Apply formatting client-side via formatNumber with isNumericString checks and safe fallback; render formattedMetricValue/formattedDelta.
- Extend unit tests for formatting cases; add e2e tests and snapshots for compact, dollar, printf, and non-numeric.
Utils:
- Introduce shared ~lib/util/formatNumber (formatting + isNumericString) with comprehensive tests.
- Refactor DataFrame columns (NumberColumn, ProgressColumn, ChartColumn) to use new util; remove inlined formatNumber from columns/utils.ts.
Proto/Types:
- proto/Metric.proto: add string format = 11.
E2E App:
- Demo examples for new format options in e2e_playwright/st_metric.py.

^{Written by Cursor Bugbot for commit d308c0a. Configure here.}

snyk-io · 2025-12-03T09:03:03Z

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

github-actions · 2025-12-03T09:03:12Z

✅ PR preview is ready!

Name	Link
📦 Wheel file	https://core-previews.s3-us-west-2.amazonaws.com/pr-13193/streamlit-1.51.0-py3-none-any.whl
📦 `@streamlit/component-v2-lib`	Download from artifacts
🕹️ Preview app	pr-13193.streamlit.app (☁️ Deploy here if not accessible)

lukasmasuch · 2025-12-03T09:03:58Z

frontend/lib/src/util/formatNumber.ts

This is mostly an extraction of the formatNumber functionality from the dataframe module to a shared module.

Copilot

Pull request overview

This PR adds support for configuring the format parameter in st.metric to control how numeric values and deltas are displayed. The implementation enables users to format numbers using predefined formats (e.g., "dollar", "percent", "compact") or custom printf-style format strings (e.g., "%.2f").

Key changes:

Added format field to the Metric protobuf message
Extended st.metric Python API with format parameter supporting predefined formats and printf-style strings
Refactored formatNumber function into a shared utility module (frontend/lib/src/util/formatNumber.ts)
Added logic in the Metric React component to conditionally apply formatting to numeric values and deltas

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`proto/streamlit/proto/Metric.proto`	Added optional `format` field to enable number formatting configuration
`lib/streamlit/elements/metric.py`	Added `format` parameter to metric function with comprehensive documentation
`lib/tests/streamlit/elements/metric_test.py`	Added unit tests for format parameter with various predefined and printf-style formats
`frontend/lib/src/util/formatNumber.ts`	Extracted and consolidated formatNumber utility from DataFrame utils into shared module
`frontend/lib/src/util/formatNumber.test.ts`	Comprehensive test coverage for formatNumber function including all format types
`frontend/lib/src/components/widgets/DataFrame/columns/utils.ts`	Removed formatNumber implementation (moved to shared utility)
`frontend/lib/src/components/widgets/DataFrame/columns/utils.test.ts`	Removed formatNumber tests (moved to new location)
`frontend/lib/src/components/widgets/DataFrame/columns/ProgressColumn.ts`	Updated import to use formatNumber from new shared utility location
`frontend/lib/src/components/widgets/DataFrame/columns/NumberColumn.ts`	Updated import to use formatNumber from new shared utility location
`frontend/lib/src/components/widgets/DataFrame/columns/ChartColumn.ts`	Updated import to use formatNumber from new shared utility location
`frontend/lib/src/components/elements/Metric/Metric.tsx`	Added conditional number formatting logic using isNumericString and formatNumber
`frontend/lib/src/components/elements/Metric/Metric.test.tsx`	Added comprehensive tests for format parameter behavior
`e2e_playwright/st_metric_test.py`	Added E2E test to verify format rendering in the UI
`e2e_playwright/st_metric.py`	Added test cases with various format types for visual verification

frontend/lib/src/components/elements/Metric/Metric.tsx

frontend/lib/src/util/formatNumber.test.ts

e2e_playwright/st_metric.py

frontend/lib/src/components/elements/Metric/Metric.tsx

e2e_playwright/st_metric_test.py

…format-in-metric

sfc-gh-bnisco · 2025-12-03T17:22:16Z

lib/streamlit/elements/metric.py

-        shorten it using packages like `millify <https://github.com/azaitsev/millify>`_
-        or `numerize <https://github.com/davidsa03/numerize>`_. E.g. ``1234`` can be
-        displayed as ``1.2k`` using ``st.metric("Short number", millify(1234))``.
+         Tip: If you want to display a large number, it may be a good idea to


question: Are all of these indentation changes intentional?

Oh, good catch... I don't think so. Not sure what happened here

…format-in-metric

lukasmasuch · 2025-12-04T00:39:16Z

lib/streamlit/elements/metric.py

-                shorten it using packages like `millify <https://github.com/azaitsev/millify>`_
-                or `numerize <https://github.com/davidsa03/numerize>`_. E.g. ``1234`` can be
-                displayed as ``1.2k`` using ``st.metric("Short number", millify(1234))``.
+        Tip: If you want to display a large number, it may be a good idea to


The existing docstring was a bit broken

OrthelT · 2025-12-04T00:56:53Z

Thank you for this! Great work.

Support configuring the format in st.metric

f83fb1f

Copilot AI review requested due to automatic review settings December 3, 2025 09:02

lukasmasuch requested a review from a team as a code owner December 3, 2025 09:02

Copilot started reviewing on behalf of lukasmasuch December 3, 2025 09:03 View session

lukasmasuch commented Dec 3, 2025

View reviewed changes

lukasmasuch added security-assessment-completed Security assessment has been completed for PR change:feature PR contains new feature or enhancement implementation impact:users PR changes affect end users labels Dec 3, 2025

Copilot finished reviewing on behalf of lukasmasuch December 3, 2025 09:05

Copilot AI reviewed Dec 3, 2025

View reviewed changes

lukasmasuch added 2 commits December 3, 2025 10:17

Update

516d06e

Update

9029ee2

graphite-app bot reviewed Dec 3, 2025

View reviewed changes

e2e_playwright/st_metric_test.py Show resolved Hide resolved

lukasmasuch added 3 commits December 3, 2025 11:03

Merge remote-tracking branch 'upstream/develop' into feature/support-…

309d33e

…format-in-metric

Fix

0f993a7

Update

d530e52

sfc-gh-bnisco approved these changes Dec 3, 2025

View reviewed changes

lukasmasuch added 2 commits December 3, 2025 20:11

Merge remote-tracking branch 'upstream/develop' into feature/support-…

b894e08

…format-in-metric

Update snapshots

d308c0a

lukasmasuch enabled auto-merge (squash) December 4, 2025 00:26

lukasmasuch and others added 2 commits December 4, 2025 01:34

Merge branch 'develop' into feature/support-format-in-metric

2744bb0

Fix test

7fed916

lukasmasuch commented Dec 4, 2025

View reviewed changes

lukasmasuch merged commit ee2af8d into develop Dec 4, 2025
43 checks passed

lukasmasuch deleted the feature/support-format-in-metric branch December 4, 2025 00:54

lukasmasuch mentioned this pull request Dec 5, 2025

format_func for st.metric #6951

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support configuring the `format` in `st.metric` #13193

Support configuring the `format` in `st.metric` #13193

lukasmasuch commented Dec 3, 2025 •

edited by cursor bot

Loading

Uh oh!

snyk-io bot commented Dec 3, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Dec 3, 2025 •

edited

Loading

Uh oh!

lukasmasuch Dec 3, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sfc-gh-bnisco Dec 3, 2025

Uh oh!

lukasmasuch Dec 3, 2025 •

edited

Loading

Uh oh!

lukasmasuch Dec 4, 2025

Uh oh!

Uh oh!

OrthelT commented Dec 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Support configuring the format in st.metric #13193

Support configuring the format in st.metric #13193

Conversation

lukasmasuch commented Dec 3, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe your changes

GitHub Issue Link (if applicable)

Testing Plan

Uh oh!

snyk-io bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Snyk checks have passed. No issues have been found so far.

Uh oh!

github-actions bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ PR preview is ready!

Uh oh!

lukasmasuch Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sfc-gh-bnisco Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

lukasmasuch Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukasmasuch Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

OrthelT commented Dec 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Support configuring the `format` in `st.metric` #13193

Support configuring the `format` in `st.metric` #13193

lukasmasuch commented Dec 3, 2025 •

edited by cursor bot

Loading

snyk-io bot commented Dec 3, 2025 •

edited

Loading

github-actions bot commented Dec 3, 2025 •

edited

Loading

lukasmasuch Dec 3, 2025 •

edited

Loading