Skip to content

text_configuration.md

Latest commit

 

History

History
420 lines (334 loc) · 7.52 KB

text_configuration.md

File metadata and controls

420 lines (334 loc) · 7.52 KB
Raw

Text Configuration Guide

Comprehensive guide for configuring text behavior in FlutterDropdownButton.text().

TextDropdownConfig Overview

The TextDropdownConfig class provides precise control over text rendering, overflow behavior, and styling in text mode.

Since 2.4.0 text mode is not limited to String: pass a label callback and any T renders as text, keeping the tooltip, the overflow handling and the default search filter.

Basic Configuration

Default Configuration

FlutterDropdownButton<String>.text(
  items: ['Short', 'Medium text', 'Very long text that might overflow'],
  onChanged: (value) {},
  // Uses TextDropdownConfig.defaultConfig by default
)

Custom Configuration

FlutterDropdownButton<String>.text(
  items: ['Option 1', 'Option 2'],
  onChanged: (value) {},
  config: TextDropdownConfig(
    overflow: TextOverflow.ellipsis,
    maxLines: 1,
    textStyle: TextStyle(fontSize: 16),
  ),
)

Text Overflow Control

Ellipsis (Default)

Shows "..." when text is too long:

TextDropdownConfig(
  overflow: TextOverflow.ellipsis,
  maxLines: 1,
)

Result: "This is a very long text t..."

Fade

Gradually fades out overflowing text:

TextDropdownConfig(
  overflow: TextOverflow.fade,
  maxLines: 1,
)

Clip

Cuts off text abruptly:

TextDropdownConfig(
  overflow: TextOverflow.clip,
  maxLines: 1,
)

Result: "This is a very long text t"

Visible

Allows text to overflow (may cause layout issues):

TextDropdownConfig(
  overflow: TextOverflow.visible,
  maxLines: 1,
)

Multi-line Text

Basic Multi-line

TextDropdownConfig(
  maxLines: 3,
  overflow: TextOverflow.ellipsis,
  softWrap: true,
)

Unlimited Lines

TextDropdownConfig(
  maxLines: null,  // No limit
  overflow: TextOverflow.visible,
  softWrap: true,
)

Explicit Line Breaks

Handle \n characters in text:

FlutterDropdownButton<String>.text(
  items: [
    'Single line',
    'Multi-line text\nwith explicit\nbreaks',
  ],
  config: TextDropdownConfig(
    maxLines: 3,
    softWrap: true,
  ),
  itemHeight: 60, // Increase height for multi-line
  onChanged: (value) {},
)

Text Styling

Basic Styling

TextDropdownConfig(
  textStyle: TextStyle(
    fontSize: 16,
    fontWeight: FontWeight.w500,
    color: Colors.black87,
  ),
  hintStyle: TextStyle(
    fontSize: 16,
    color: Colors.grey[500],
    fontStyle: FontStyle.italic,
  ),
)

Selected Item Styling

TextDropdownConfig(
  textStyle: TextStyle(fontSize: 16),
  selectedTextStyle: TextStyle(
    fontSize: 16,
    fontWeight: FontWeight.bold,
    color: Colors.blue[700],
  ),
)

Custom Font

TextDropdownConfig(
  textStyle: TextStyle(
    fontFamily: 'Roboto',
    fontSize: 14,
    letterSpacing: 0.5,
  ),
)

Text Alignment

Left Align (Default)

TextDropdownConfig(
  textAlign: TextAlign.start,
)

Center Align

TextDropdownConfig(
  textAlign: TextAlign.center,
)

Right Align

TextDropdownConfig(
  textAlign: TextAlign.end,
)

Justify

TextDropdownConfig(
  textAlign: TextAlign.justify,
  maxLines: null,
  softWrap: true,
)

Predefined Configurations

Default Single-line

FlutterDropdownButton<String>.text(
  config: TextDropdownConfig.defaultConfig,
  // Equivalent to:
  // TextDropdownConfig(
  //   overflow: TextOverflow.ellipsis,
  //   maxLines: 1,
  // )
)

Multi-line Display

FlutterDropdownButton<String>.text(
  config: TextDropdownConfig.multiLine,
  itemHeight: 80, // Increase height for multi-line
  // Equivalent to:
  // TextDropdownConfig(
  //   maxLines: null,
  //   overflow: TextOverflow.visible,
  //   softWrap: true,
  // )
)

Center Aligned

FlutterDropdownButton<String>.text(
  config: TextDropdownConfig.centered,
  // Equivalent to:
  // TextDropdownConfig(
  //   textAlign: TextAlign.center,
  // )
)

Fade Overflow

FlutterDropdownButton<String>.text(
  config: TextDropdownConfig.fadeOverflow,
  // Equivalent to:
  // TextDropdownConfig(
  //   overflow: TextOverflow.fade,
  // )
)

Advanced Configuration

RTL Support

TextDropdownConfig(
  textDirection: TextDirection.rtl,
  textAlign: TextAlign.start, // Will align to right in RTL
)

Accessibility

TextDropdownConfig(
  semanticsLabel: 'Fruit selection dropdown',
  textScaler: TextScaler.linear(1.2), // Larger text for accessibility
)

semanticsLabel describes the button. A screen reader announces it alongside the selected value — "Fruit selection dropdown, Banana" — not in place of it. Menu items do not take the label — each announces its own text, plus whether it is the chosen one (selected), which is the only place that state exists for a screen reader: on screen it is a colour.

Locale-specific Rendering

TextDropdownConfig(
  locale: Locale('ar'), // Arabic locale
  textDirection: TextDirection.rtl,
)

Dynamic Configuration

Responsive Text Size

TextDropdownConfig buildConfig(BuildContext context) {
  final screenWidth = MediaQuery.of(context).size.width;
  final isTablet = screenWidth > 600;
  
  return TextDropdownConfig(
    textStyle: TextStyle(
      fontSize: isTablet ? 18 : 14,
    ),
    maxLines: isTablet ? 2 : 1,
  );
}

Theme-based Configuration

TextDropdownConfig buildThemedConfig(BuildContext context) {
  final theme = Theme.of(context);
  
  return TextDropdownConfig(
    textStyle: theme.textTheme.bodyMedium,
    hintStyle: theme.textTheme.bodyMedium?.copyWith(
      color: theme.hintColor,
    ),
    selectedTextStyle: theme.textTheme.bodyMedium?.copyWith(
      color: theme.primaryColor,
      fontWeight: FontWeight.w600,
    ),
  );
}

Common Use Cases

Search Dropdown with Long Options

FlutterDropdownButton<String>.text(
  items: [
    'Apple Inc. (AAPL)',
    'Microsoft Corporation (MSFT)',
    'Alphabet Inc. Class A (GOOGL)',
  ],
  maxWidth: 200,
  config: TextDropdownConfig(
    overflow: TextOverflow.ellipsis,
    textStyle: TextStyle(fontSize: 14),
  ),
  onChanged: (value) {},
)

Multi-line Description Dropdown

FlutterDropdownButton<String>.text(
  items: [
    'Option 1\nShort description',
    'Option 2\nA longer description that explains the purpose of this option',
  ],
  itemHeight: 60,
  config: TextDropdownConfig(
    maxLines: 2,
    textStyle: TextStyle(fontSize: 14, height: 1.3),
    overflow: TextOverflow.ellipsis,
  ),
  onChanged: (value) {},
)

Language Selector

FlutterDropdownButton<String>.text(
  items: ['English', '中文', 'العربية', 'עברית'],
  config: TextDropdownConfig(
    textAlign: TextAlign.center,
    textStyle: TextStyle(fontSize: 16),
  ),
  onChanged: (value) {},
)

Best Practices

1. Match Item Height to Content

// For single-line text
itemHeight: 48

// For two-line text
itemHeight: 64

// For three-line text  
itemHeight: 80

2. Consistent Text Scaling

TextDropdownConfig(
  textScaler: MediaQuery.textScalerOf(context),
)

3. Readable Text Contrast

Ensure text is readable against the background:

TextDropdownConfig(
  textStyle: TextStyle(
    color: Theme.of(context).textTheme.bodyMedium?.color,
  ),
)

4. Overflow Handling

Choose appropriate overflow behavior for your content:

  • Ellipsis: Best for single-line critical text
  • Fade: Good for less important overflow text
  • Multi-line: For descriptive or detailed content