Add preferNative option

README.md

@@ -36,6 +36,7 @@ function Title() {
 
 - **`as`** (_optional_): The HTML tag to be used to wrap the text content. Default to `span`.
 - **`ratio`** (_optional_): The ratio of “balance-ness”, 0 <= ratio <= 1. Default to `1`.
+- **`preferNative`** (_optional_): An option to skip the re-balance logic and use the native CSS text-balancing if supported. Default to `true`.
 - **`nonce`** (_optional_): The [nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) attribute to allowlist inline script injection by the component.
 
 ### `<Provider>`

src/index.tsx

@@ -130,6 +130,12 @@ interface BalancerOwnProps<
    * @default 1
    */
   ratio?: number
+  /**
+   * An option to skip the re-balance logic
+   * and use the native CSS text-balancing if supported.
+   * @default true
+   */
+  preferNative?: boolean
   /**
    * The nonce attribute to allowlist inline script injection by the component.
    */
@@ -145,16 +151,31 @@ type BalancerProps<ElementType extends React.ElementType> =
  * An optional provider to inject the global relayout function, so all children
  * Balancer components can share it.
  */
-const BalancerContext = React.createContext<boolean>(false)
+const BalancerContext = React.createContext<{
+  preferNative: boolean
+  hasProvider: boolean
+}>({ preferNative: true, hasProvider: false })
 const Provider: React.FC<{
+  /**
+   * An option to skip the re-balance logic
+   * and use the native CSS text-balancing if supported.
+   * @default true
+   */
+  preferNative?: boolean
   /**
    * The nonce attribute to allowlist inline script injection by the component
    */
   nonce?: string
   children?: React.ReactNode
-}> = ({ nonce, children }) => {
+}> = ({ preferNative = true, nonce, children }) => {
+  const contextValue = React.useMemo(() => {
+    return {
+      preferNative,
+      hasProvider: true,
+    }
+  }, [preferNative])
   return (
-    <BalancerContext.Provider value={true}>
+    <BalancerContext.Provider value={contextValue}>
       {createScriptElement(false, nonce)}
       {children}
     </BalancerContext.Provider>
@@ -163,30 +184,32 @@ const Provider: React.FC<{
 
 const Balancer = <ElementType extends React.ElementType = React.ElementType>({
   ratio = 1,
+  preferNative = true,
   nonce,
   children,
   ...props
 }: BalancerProps<ElementType>) => {
   const id = useId()
   const wrapperRef = React.useRef<WrapperElement>()
-  const hasProvider = React.useContext(BalancerContext)
+  const contextValue = React.useContext(BalancerContext)
+  const preferNativeBalancing = preferNative && contextValue.preferNative
   const Wrapper: React.ElementType = props.as || 'span'
 
   // Re-balance on content change and on mount/hydration.
   useIsomorphicLayoutEffect(() => {
     // Skip if the browser supports text-balancing natively.
-    if (self[SYMBOL_NATIVE_KEY] === 1) return
+    if (preferNativeBalancing && self[SYMBOL_NATIVE_KEY] === 1) return
 
     if (wrapperRef.current) {
       // Re-assign the function here as the component can be dynamically rendered, and script tag won't work in that case.
       ;(self[SYMBOL_KEY] = relayout)(0, ratio, wrapperRef.current)
     }
-  }, [children, ratio])
+  }, [children, preferNativeBalancing, ratio])
 
   // Remove the observer when unmounting.
   useIsomorphicLayoutEffect(() => {
     // Skip if the browser supports text-balancing natively.
-    if (self[SYMBOL_NATIVE_KEY] === 1) return
+    if (preferNativeBalancing && self[SYMBOL_NATIVE_KEY] === 1) return
 
     return () => {
       if (!wrapperRef.current) return
@@ -197,7 +220,7 @@ const Balancer = <ElementType extends React.ElementType = React.ElementType>({
       resizeObserver.disconnect()
       delete wrapperRef.current[SYMBOL_OBSERVER_KEY]
     }
-  }, [])
+  }, [preferNativeBalancing])
 
   if (process.env.NODE_ENV === 'development') {
     // In development, we check `children`'s type to ensure we are not wrapping
@@ -232,14 +255,14 @@ To:
           display: 'inline-block',
           verticalAlign: 'top',
           textDecoration: 'inherit',
-          textWrap: 'balance',
+          textWrap: preferNative ? 'balance' : 'initial',
         }}
         suppressHydrationWarning
       >
         {children}
       </Wrapper>
       {createScriptElement(
-        hasProvider,
+        contextValue.hasProvider,
         nonce,
         `self.${SYMBOL_KEY}("${id}",${ratio})`
       )}

website/src/sections/CustomBalanceRatio.tsx

@@ -44,11 +44,13 @@ export default function CustomBalanceRatio() {
                 </Balancer>
               </h2>
               <h2 className='ratio-title'>
-                <Balancer ratio={currentRatio}>
+                <Balancer ratio={currentRatio} preferNative={false}>
                   The quick brown fox jumps over the lazy dog
                 </Balancer>
               </h2>
-              <code>{`<Balancer ratio={${ratio.toFixed(2)}}>`}</code>
+              <code>{`<Balancer ratio={${ratio.toFixed(
+                2
+              )}} preferNative={false}>`}</code>
             </div>
           </div>
         </div>
@@ -88,7 +90,8 @@ export default function CustomBalanceRatio() {
           text-wrap: balance
         </BlankLink>
         ) is available, React Wrap Balancer will use it instead. And the `ratio`
-        option will be ignored in that case.
+        option will be ignored in that case. You can provide the `preferNative`
+        option to opt out.
       </p>
     </>
   )