auto_size_text

Use AutoSizeGroup to ensure multiple AutoSizeText widgets in the same group share the same font size. The group will adjust all members to match the member with the smallest effective font size.

Important: Do not create a new instance of AutoSizeGroup inside a build method. You must persist the instance (e.g., in a StatefulWidget's state) or use an AutoSizeGroupBuilder to avoid unnecessary re-calculations and synchronization issues.

// In a StatefulWidget state:
var myGroup = AutoSizeGroup();

// In build method:
Column(
  children: [
    AutoSizeText(
      'Text 1',
      group: myGroup,
    ),
    AutoSizeText(
      'Text 2',
      group: myGroup,
    ),
    ],
)

The AutoSizeText widget behaves like a standard Flutter Text widget but automatically resizes the font to fit within its available bounds.

Note: AutoSizeText requires bounded constraints (width and height) to function correctly. If placed inside unconstrained widgets like a Row or Column without an Expanded or SizedBox wrapper, it will overflow instead of resizing.

AutoSizeText(
  'The text to display',
  style: TextStyle(fontSize: 20),
  maxLines: 2,
)

You can control how the font size scales using several parameters. Note that if presetFontSizes is provided, these parameters are ignored.

• minFontSize: The minimum font size allowed (defaults to 12).
• maxFontSize: The maximum font size allowed (defaults to double.infinity).
• stepGranularity: The step size for font size adaptation. The text scales uniformly between minFontSize and maxFontSize in increments of this value. (Defaults to 1).
• presetFontSizes: A list of predefined font sizes to choose from. Important: These must be provided in descending order.

If AutoSizeText is not resizing or is overflowing, it likely lacks bounded constraints. This often happens when placed inside a Row, Column, or ListView.

Solution: Wrap the AutoSizeText in an Expanded widget (if inside a Row or Column) or a SizedBox with fixed dimensions to provide the necessary constraints.

// Correct way to use inside a Row
Row(
  children: <Widget>[
    Expanded( // Constrains AutoSizeText to the width of the Row
      child: AutoSizeText(
        'Here is a very long text, which should be resized',
        maxLines: 1,
      )
    ),
  ],
)

When using AutoSizeText.rich(), if the TextSpan has a large font size but the AutoSizeText widget itself has no style defined, it defaults to a small font size (e.g., 14). The minFontSize (default 12) then prevents the text from scaling down effectively.

Solution:

1. Provide a style: TextStyle(fontSize: ...) to the AutoSizeText constructor that matches your intended scale.
2. Or, set minFontSize: 0 and decrease stepGranularity (e.g., 0.1) for smoother scaling.

// Correct way to handle large rich text scaling
AutoSizeText.rich(
  TextSpan(
    text: 'Text that will be resized correctly',
    style: TextStyle(fontSize: 200),
  ),
  minFontSize: 0,
  stepGranularity: 0.1,
)

You can constrain the range of the resulting font size using minFontSize and maxFontSize.

• minFontSize: The smallest allowed font size. If the text cannot fit even at this size, it will be handled according to the overflow property. The default is 12.
• maxFontSize: The largest allowed font size. This is useful when inheriting font sizes from a parent TextStyle and wanting to cap them.

Note: These parameters are ignored if presetFontSizes is provided.

AutoSizeText(
  'A really long String',
  style: TextStyle(fontSize: 30),
  minFontSize: 18,
  maxLines: 4,
  overflow: TextOverflow.ellipsis,
)

To use TextSpan or other rich text elements, use the AutoSizeText.rich() constructor.

Font Size Calculation: The fontSize provided in the style parameter of AutoSizeText (or the inherited fontSize) acts as the reference for scaling.

Common Pitfall: If you use AutoSizeText.rich() with a TextSpan that has a very large fontSize but no style on the AutoSizeText itself, the widget might fall back to a default small font size, causing the minFontSize constraint to trigger prematurely. To fix this, either set the minFontSize to 0 or provide a matching style to the AutoSizeText constructor.

AutoSizeText.rich(
  TextSpan(text: 'A really long String'),
  style: TextStyle(fontSize: 20),
  minFontSize: 5,
)

If the text cannot fit within its bounds even at the minFontSize, you can provide an overflowReplacement widget to be displayed instead of the scaled text. This is useful for preventing text from becoming unreadable.

AutoSizeText(
  'A String tool long to display without extreme scaling or overflow.',
  maxLines: 1,
  overflowReplacement: Text('Sorry String too long'),
)

If you want the text to only snap to specific font sizes, use the presetFontSizes parameter. When this is set, minFontSize, maxFontSize, and stepGranularity are ignored.

Requirement: The list of sizes in presetFontSizes must be provided in descending order.

AutoSizeText(
  'A really long String',
  presetFontSizes: [40, 20, 14],
  maxLines: 4,
)

stepGranularity defines the decrement step used when the widget tries different font sizes to find a fit.

• For better performance, keep this value at or above 1.
• If you have a very large font size range, increasing this value can improve performance.
• If you are using a very small minFontSize (e.g., 0), you should decrease stepGranularity (e.g., 0.1) to ensure smooth resizing.

AutoSizeText(
  'A really long String',
  style: TextStyle(fontSize: 40),
  minFontSize: 10,
  stepGranularity: 10,
  maxLines: 4,
  overflow: TextOverflow.ellipsis,
)

If the text exceeds its bounds and cannot be resized further to fit, you can specify a widget to be displayed instead of the text using overflowReplacement.

Note: You cannot use both overflow and overflowReplacement simultaneously.