Adaptive Text

A Flutter widget that intelligently adapts text display based on available space with a three-tier fallback strategy:

Reflow to multiple lines (for multi-word text only)
Scale down font size (maximum 25% reduction by default)
Truncate with ellipsis (as last resort)

Perfect for responsive UIs, dynamic content, and accessibility-friendly applications that need to handle varying text lengths and screen sizes gracefully.

Features

🎯 Smart text fitting with three-tier fallback strategy
🔄 Smooth animations between different display modes
♿ Accessibility support with semantic announcements
📱 Text scaler aware - works with system font scaling
🎨 Highly customizable - control animation, scaling limits, and overflow behavior
🚀 Performance optimized with intelligent caching
🐛 Debug mode for development and troubleshooting

Installation

Add this to your pubspec.yaml:

dependencies:
  adaptive_text: ^1.0.0

Then run:

flutter pub get

Quick Start

import 'package:adaptive_text/adaptive_text.dart';

// Basic usage
AdaptiveText(
  'This text will adapt to available space',
  style: TextStyle(fontSize: 24),
)

// Convert existing Text widget
Text(
  'Your existing text',
  style: TextStyle(fontSize: 18),
).toAdaptive()

Usage Examples

Basic Adaptive Text

AdaptiveText(
  'This text will automatically adapt to fit the available space',
  style: TextStyle(
    fontSize: 20,
    fontWeight: FontWeight.bold,
  ),
  maxLines: 2,
)

Customized Behavior

AdaptiveText(
  'Custom adaptive text with specific parameters',
  style: TextStyle(fontSize: 18),
  maxLines: 3,
  maxScaleReduction: 0.3, // Allow up to 30% font size reduction
  animationDuration: Duration(milliseconds: 300),
  animationCurve: Curves.easeInOut,
  overflow: TextOverflow.fade, // Use fade instead of ellipsis
)

Debug Mode

AdaptiveText(
  'Debug this text adaptation',
  style: TextStyle(fontSize: 16),
  debugMode: true, // Enables console debugging output
)

Using the Extension

// Convert any existing Text widget
Text(
  'Your existing text',
  style: TextStyle(fontSize: 24),
  textAlign: TextAlign.center,
).toAdaptive(
  animationDuration: Duration(milliseconds: 200),
  maxScaleReduction: 0.2,
)

How It Works

Three-Tier Adaptation Strategy

Line Wrapping (Multi-word text only)
- Text flows to multiple lines within the available space
- Respects maxLines parameter
- Only applies to text with multiple words
Font Scaling
- Gradually reduces font size while maintaining readability
- Default maximum reduction: 25% of original size
- Smooth animated transitions between scales
- Preserves text style properties
Truncation
- Last resort when text cannot fit even when scaled
- Uses ellipsis (or custom overflow) to indicate truncated content
- Announces truncation to screen readers for accessibility

Text Scaler Support

AdaptiveText automatically works with Flutter's text scaling features:

MediaQuery(
  data: MediaQuery.of(context).copyWith(
    textScaler: TextScaler.linear(1.5), // 150% text scaling
  ),
  child: AdaptiveText(
    'This text respects system text scaling preferences',
    style: TextStyle(fontSize: 16),
  ),
)

API Reference

AdaptiveText Properties

Property	Type	Default	Description
`text`	`String`	required	The text to display
`style`	`TextStyle?`	null	Text style (fontSize, fontFamily, etc.)
`textAlign`	`TextAlign?`	null	Text alignment
`maxLines`	`int?`	null	Maximum number of lines (null = unlimited)
`overflow`	`TextOverflow`	`TextOverflow.ellipsis`	How to handle text overflow
`animationDuration`	`Duration`	`Duration(milliseconds: 200)`	Animation duration for scaling
`animationCurve`	`Curve`	`Curves.easeInOut`	Animation curve for scaling
`maxScaleReduction`	`double`	`0.25`	Maximum font size reduction (0.0-1.0)
`debugMode`	`bool`	`false`	Enable debug logging

Extension Method

extension AdaptiveTextExtension on Text {
  AdaptiveText toAdaptive({
    Duration animationDuration = const Duration(milliseconds: 200),
    Curve animationCurve = Curves.easeInOut,
    double maxScaleReduction = 0.25,
    bool debugMode = false,
  })
}

Accessibility Features

Semantic announcements: Automatically announces when text is truncated
Screen reader support: Provides appropriate labels for truncated content
Text scaler compatibility: Respects system font scaling preferences
Keyboard navigation: Works seamlessly with keyboard navigation

Performance Considerations

Intelligent caching: Avoids recalculation when constraints haven't changed
Optimized text measurement: Minimizes TextPainter operations
Efficient animations: Uses Flutter's built-in animation framework
Memory efficient: Disposes resources properly

Troubleshooting

Text appears truncated even with plenty of space

This usually happens when the widget receives unbounded constraints (e.g., inside a Row without Expanded).

Solution: Wrap with Expanded or Flexible:

Row(
  children: [
    Expanded(
      child: AdaptiveText('Your text here'),
    ),
  ],
)

Animation not working

Enable debug mode to see what's happening:

AdaptiveText(
  'Your text',
  debugMode: true, // Check console for debug info
)

Text scaler issues

Ensure your app properly supports text scaling:

MaterialApp(
  builder: (context, child) {
    return MediaQuery(
      data: MediaQuery.of(context).copyWith(
        textScaler: MediaQuery.textScalerOf(context),
      ),
      child: child!,
    );
  },
  // ... rest of your app
)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests if applicable
Ensure the code passes all tests (flutter test)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you find this package helpful, please consider:

⭐ Starring the repository on GitHub
👍 Liking the package on pub.dev
🐛 Reporting issues or bugs
💡 Suggesting new features

For questions or support, please open an issue on GitHub.