From 971cb70c40e1b0889f834988d6f0d2dca64ffdb2 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 May 2025 15:28:18 -0700
Subject: [PATCH] Add text-wrap balance and pretty to complement existing
 white-space utils. In v6 we'll replace with all text-wrap utilities.

---
 scss/_utilities.scss                     |  8 ++++++++
 site/src/content/docs/utilities/text.mdx | 16 ++++++++++++++--
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 696f906ec9c4..aa39ddcce7ab 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -565,6 +565,14 @@ $utilities: map-merge(
         nowrap: nowrap,
       )
     ),
+    "text-wrap": (
+      property: text-wrap,
+      class: text,
+      values: (
+        balance: balance,
+        pretty: pretty,
+      )
+    ),
     "word-wrap": (
       property: word-wrap word-break,
       class: text,
diff --git a/site/src/content/docs/utilities/text.mdx b/site/src/content/docs/utilities/text.mdx
index 2cbf73277053..8dbe68801a23 100644
--- a/site/src/content/docs/utilities/text.mdx
+++ b/site/src/content/docs/utilities/text.mdx
@@ -26,8 +26,8 @@ Note that we don’t provide utility classes for justified text. While, aestheti
 
 Wrap text with a `.text-wrap` class.
 
-<Example code={`<div class="badge text-bg-primary text-wrap" style="width: 6rem;">
-    This text should wrap.
+<Example code={`<div class="text-wrap bg-body-secondary border" style="width: 8rem;">
+    This snippet of text should wrap.
   </div>`} />
 
 Prevent text from wrapping with a `.text-nowrap` class.
@@ -36,6 +36,18 @@ Prevent text from wrapping with a `.text-nowrap` class.
     This text should overflow the parent.
   </div>`} />
 
+Use `.text-balance` to balance evenly distribute text across multiple lines. This is computationally expensive and is thus limited by the Chromium to six lines and by Firefox to ten lines.
+
+<Example code={`<div class="text-balance mx-auto" style="width: 20rem;">
+    This text should be balanced. Here we’re writing a longer snippet of text to form a paragraph and demonstrate how the text wraps.
+  </div>`} />
+
+Use `.text-pretty` to prevent single words their own line (orphans). **Pretty text wrapping is not fully supported in Safari and Firefox at the moment.**
+
+<Example code={`<div class="text-pretty mx-auto" style="width: 20rem;">
+    This text should be pretty. Here we’re writing a longer snippet of text to form a paragraph and demonstrate how the text wraps.
+  </div>`} />
+
 ## Word break
 
 Prevent long strings of text from breaking your components’ layout by using `.text-break` to set `word-wrap: break-word` and `word-break: break-word`. We use `word-wrap` instead of the more common `overflow-wrap` for wider browser support, and add the deprecated `word-break: break-word` to avoid issues with flex containers.