Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

RichText shows text in the wrong colour, size or scale

ErrorRichText ignores the theme text colour or size

Short answer

RichText does not read the text style around it. Its documentation says text must be explicitly styled. So spans look different from a Text widget with the same words, and the text does not follow the system font size either. Use Text.rich, or hand RichText the ambient style and text scaler yourself.

  • Applies to Flutter 3.35, Dart 3.9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the RichText widgets in the app and see how each root TextSpan is styled. A root span without a style is the usual start of the problem.

    grep -rn -A4 "RichText(" lib/
  2. 2Match what you see, then jump to its fix

    1. 1The same words in a Text widget look right, and in RichText they miss the theme's colour, size or fontRichText does not inherit the surrounding text styleFix
    2. 2Text widgets grow when the phone's font size is raised in settings, but the RichText line stays the sameRichText does not follow the system font sizeFix
    3. 3'textScaleFactor' is deprecated and shouldn't be used. Use textScaler instead.Old code still sets textScaleFactorFix
    4. 4A child span ignores the colour or size set on its parent span, while its siblings do notA child span's TextStyle has inherit set to falseFix

What does the error look like?

  • RichText ignores the theme text colour or size
  • 'textScaleFactor' is deprecated and shouldn't be used. Use textScaler instead.

Cause 1 of 4

RichText does not inherit the surrounding text style

1Check

The RichText documentation says text in it must be explicitly styled, and advises using DefaultTextStyle for defaults. The Text widget does that step for you, which is why the two differ. Check whether the root span has a style.

grep -rn "DefaultTextStyle" lib/

2Fix

Switch to Text.rich, which takes its default style from DefaultTextStyle and still lets each span set its own. If you keep RichText, set the ambient style on the root span.

// Option 1: Text.rich inherits the ambient style
Text.rich(
  TextSpan(
    text: 'Total: ',
    children: const [
      TextSpan(text: '42', style: TextStyle(fontWeight: FontWeight.bold)),
    ],
  ),
)

// Option 2: keep RichText and pass the ambient style yourself
RichText(
  text: TextSpan(
    text: 'Total: ',
    style: DefaultTextStyle.of(context).style,
    children: const [
      TextSpan(text: '42', style: TextStyle(fontWeight: FontWeight.bold)),
    ],
  ),
)

3Verify

Hot reload and compare the line with a plain Text widget next to it. Colour, size and font now match.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 2 of 4

RichText does not follow the system font size

1Check

The Text widget takes its scaler from MediaQuery, which reflects the user's accessibility setting. The RichText constructor defaults textScaler to TextScaler.noScaling, so by default it ignores that setting.

grep -rn "textScaler\|textScaleFactor" lib/

2Fix

Pass the ambient scaler to RichText, or use Text.rich, which handles it.

RichText(
  textScaler: MediaQuery.textScalerOf(context),
  text: TextSpan(
    text: 'Total: ',
    style: DefaultTextStyle.of(context).style,
  ),
)

3Verify

Raise the font size in the device settings and reopen the screen. The line grows with the rest.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 3 of 4

Old code still sets textScaleFactor

1Check

The docs mark RichText.textScaleFactor as deprecated, to be removed in a future version, in favour of textScaler. The scaling it controls is the same thing as in the previous cause.

grep -rn "textScaleFactor" lib/

2Fix

Replace the argument with textScaler. To follow the user's setting, use the ambient scaler; to turn scaling off on purpose, use TextScaler.noScaling.

// before
RichText(textScaleFactor: 1.0, text: span)

// after: follow the system setting
RichText(textScaler: MediaQuery.textScalerOf(context), text: span)

// or: no scaling on purpose
RichText(textScaler: TextScaler.noScaling, text: span)

3Verify

Run the analyzer. The deprecation message is gone.

dart analyze

Confirmed by api.flutter.dev

Did this fix it?

Cause 4 of 4

A child span's TextStyle has inherit set to false

1Check

A child span can override its parent's style, even partly. The TextStyle docs say that inherit tells whether null values can be replaced with values of another style when merged. If it is false, merging returns the child's style as it is, so nothing is taken from the parent.

grep -rn "inherit: false" lib/

2Fix

Remove inherit: false from the span's style, or set every property you need on that span.

// before
const TextSpan(text: '42', style: TextStyle(inherit: false, fontWeight: FontWeight.bold))

// after
const TextSpan(text: '42', style: TextStyle(fontWeight: FontWeight.bold))

3Verify

The span now takes colour and size from its parent and adds only the weight.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Use Text.rich for mixed styles by default, and RichText only when you need its extra options.
  • Keep one small widget for your mixed-style lines, so the style and scaler are set in one place.
  • Run dart analyze in CI, so deprecated arguments such as textScaleFactor are found early.
  • Test one screen at a large system font size before each release.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.