Text widget in Flutter

What is a Text widget in Flutter?

Text is a Flutter widget that displays a string on screen using a single, uniform style, making it the default way to render any label, heading, or paragraph in a Material or Cupertino app.

For text that requires multiple styles within the same block, Text.rich accepts a TextSpan tree instead of a plain string. Unlike TextField, which allows users to enter and edit text, Text is used to display fixed, non-editable text.

Key facts at a glance

• Text in Flutter is part of the core widgets library and requires no additional package.
• Its style property takes a single TextStyle; for mixed styles in one block, use Text.rich with TextSpan instead.
• overflow determines how text is handled when it exceeds the available space: clip, fade, ellipsis, or visible.
• softWrap determines whether text can wrap onto multiple lines, while maxLines limits the number of lines that can be displayed.
• textScaleFactor is deprecated in favor of textScaler, which supports nonlinear text scaling for accessibility.
• If no style is specified, Text inherits its style from the nearest DefaultTextStyle.

How do I style and color a Text widget in Flutter?

Pass a TextStyle to style for color, size, and weight.

import 'package:flutter/material.dart';

class SectionHeading extends StatelessWidget {
  const SectionHeading({super.key, required this.label});

  final String label;

  @override
  Widget build(BuildContext context) {
    return Text(
      label,
      style: const TextStyle(
        color: Colors.deepPurple,
        fontSize: 20,
        fontWeight: FontWeight.w600,
      ),
    );
  }
}

For app-wide consistency, prefer using styles from Theme.of(context).textTheme rather than hardcoding the same TextStyle across multiple widgets.

How do I wrap or truncate long text in Flutter?

Use softWrap, maxLines, and overflow to control how Text behaves when its content does not fit the available space. By default, text can wrap onto multiple lines. Set softWrap: false to prevent wrapping and keep the text on a single line.

For example, to limit a description to two lines and show an ellipsis when additional text does not fit:

Text(
  'A long product description that should truncate cleanly '
  'instead of overflowing the card layout underneath it.',
  maxLines: 2,
  overflow: TextOverflow.ellipsis,
),

Here, maxLines: 2 limits the text to two lines, while TextOverflow.ellipsis displays an ellipsis when the text cannot fit within those lines.

Keep in mind that Text needs appropriate constraints from its parent to determine when text overflows. For example, when placing text inside a Row, wrap it with Expanded or Flexible if it needs to use the remaining horizontal space:

Row(
  children: [
    const Icon(Icons.info),
    const SizedBox(width: 8),
    Expanded(
      child: Text(
        'A long piece of text that needs to fit inside the row.',
        maxLines: 2,
        overflow: TextOverflow.ellipsis,
      ),
    ),
  ],
),

Without appropriate width constraints, maxLines and overflow may not behave as expected, and a Row can produce a horizontal overflow.

When should I use Text – and when TextField or RichText instead?

Use Text when

• The content is fixed or comes from app state, but the user does not edit it directly.
• A single text style covers the whole string.
• You need built-in accessibility semantics for a label or heading.

Use something else when

• The user needs to type or edit the content – use TextField in Flutter instead.
• Different parts of the same block need different styles or interactive spans – use Text.rich with TextSpan, or RichText directly for lower-level control.
• The text needs to flow around an image or another widget – RichText inside a Wrap handles that better than Text alone.

Best practices

1. Pull styles from Theme.of(context).textTheme instead of hardcoding TextStyle values across screens.
2. Use maxLines and overflow deliberately when text needs to fit within a constrained layout. Use maxLines to limit the number of lines and overflow to control how content that does not fit is handled.
3. Use textScaler, not the deprecated textScaleFactor, when a widget needs to respond to system font scaling manually.
4. Use Text.rich for mixed formatting or interactive spans within a paragraph instead of composing it from multiple Text widgets. Individual TextSpans can have their own styles and GestureRecognizers for interactions such as links or tappable phrases.
5. Set semanticsLabel when the visual representation does not convey the intended meaning to assistive technologies, such as when text uses symbols, abbreviations, or decorative characters that may not be read as intended.

Common mistakes

• Using the deprecated textScaleFactor instead of textScaler. textScaleFactor is deprecated as of Flutter 3.12; use textScaler for programmatic control over text scaling.
• Placing a Text directly inside a Row without constraining its width. This can cause a RenderFlex overflow when the text is longer than the available space. overflow: TextOverflow.ellipsis alone does not provide the missing constraint. Wrap the Text in Expanded or Flexible first; then use maxLines and overflow to control how text that does not fit is handled.
• Leaving overflow unset when text may exceed a fixed-width constraint. The default is TextOverflow.clip, so content that does not fit may be clipped without an explicit visual indication that text is missing. Use an appropriate overflow value, such as TextOverflow.ellipsis, when truncation should be visible.
• Using multiple Text widgets in a Row to mix styles. For text that should flow as a single paragraph, use Text.rich with TextSpan instead.
• Hardcoding font sizes without considering text scaling. Respecting the system's text scaling settings helps keep text readable for users who need larger text.