RichText shows text in the wrong colour, size or scale
RichText ignores the theme text colour or sizeShort 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.
Fix it fast
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/2Match what you see, then jump to its fix
- 1
The 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
Text 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
'textScaleFactor' is deprecated and shouldn't be used. Use textScaler instead.Old code still sets textScaleFactorFix - 4
A 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
- 1
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 runConfirmed by api.flutter.dev
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 runConfirmed by api.flutter.dev
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 analyzeConfirmed by api.flutter.dev
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 runConfirmed by api.flutter.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
AudioCache has no play method after updating audioplayers
The method 'play' isn't defined for the type 'AudioCache'.
Since audioplayers 1.0, AudioCache only turns asset files into local files and caches them.
2 causes, each with a fixMobile apps
Flutter Bloc throws that emit was called after the event handler completed
emit was called after an event handler completed normally.
Each on<Event> handler gets its own Emitter, and it stops working the moment the handler's returned Future completes.
2 causes, each with a fixMobile apps
analysis_options.yaml: the URI it includes can't be found
include_file_not_found
The analyzer reports include_file_not_found when the file named after include: in analysis_options.yaml does not resolve.
2 causes, each with a fixMobile apps
Dart error: the body might complete normally and return null for a non-nullable type
body_might_complete_normally
Dart found a path through your function or callback that reaches the closing brace without a return.
3 causes, each with a fixMobile apps
Dart throws ConcurrentModificationError while looping over a list
ConcurrentModificationError
Dart throws this when a collection changes size while something iterates it.
2 causes, each with a fixMobile apps
Dart cannot turn a compact timestamp like 20201101153000 into a DateTime
FormatException: Invalid date format
DateTime.parse accepts a subset of ISO 8601, and a time part must be introduced by T or a space.
2 causes, each with a fix