Skip to content

Flutter's text rendering has different letter spacing from iOS native #150824

Open

Description

@dkwingsmt

Flutter's Text() has noticeably different letter spacing from iOS's Text() by default.

Background

iOS renders text with "SF Pro Text" font for font size <20, and "SF Pro Display" font for font size >= 20. In Flutter they're called "CupertinoSystemText" and "CupertinoSystemDisplay" respectively.

Comparison with current Flutter

(light grey Flutter, black native iOS)
image

Adjustment

I tried to apply letterSpacing to Flutter's text to get a result close to the native one. The needed adjustment turns out to be a non-linear curve, which is interpolated as a cubic polynomial.

image image

Comparison after adjustment

(light grey Flutter, black native iOS)
image

(Yes, I know line height at small font size still deviates noticeably.)

Note

  • If I understand correctly, Flutter's text rendering is handled by Skia, which delegates text shaping to HarfBuzz. There's an issue on HarfBuzz (link), which complained about HarfBuzz's text tracking deviates from that of macOS in 2019. Although I don't quite get the content in that page and whether the issue was considered fixed.

Reproduction code

Dart code
import 'dart:math';
import 'package:flutter/cupertino.dart';

void main() => runApp(const Main());

class Main extends StatelessWidget {
  const Main({super.key});

  @override
  Widget build(BuildContext context) {
    return CupertinoPageScaffold(
      child: SafeArea(
        child: Center(
          child: Transform.translate(
            offset: const Offset(0, -0),
            child: Container(
              width: 400,
              height: 500,
              decoration: BoxDecoration(
                border: Border.all(),
              ),
              child: Center(
                child: Column(
                  mainAxisAlignment: MainAxisAlignment.center,
                  children: <Widget>[
                    ...<double>[3, 4, 5, 7, 8, 9, 10, 11, 13, 15, 17, 19].map(
                      (double i) => Text(
                        'CupertinoSystemText size ${i.round()}',
                        style: TextStyle(
                          fontFamily: 'CupertinoSystemText',
                          fontSize: i,
                          letterSpacing: smallFontSpacingMap(i),
                        ),
                      )
                    ),
                    ...<double>[20, 22, 25, 28, 32, 36].map(
                      (double i) => Text(
                        'SystemDisplay size ${i.round()}',
                        style: TextStyle(
                          fontFamily: 'CupertinoSystemDisplay',
                          fontSize: i,
                          letterSpacing: bigFontSpacingMap(i),
                        ),
                      )
                    ),
                  ],
                ),
              ),
            ),
          ),
        ),
      ),
    );
  }
}

double smallFontSpacingMap(double i) {
  return switch (i) {
    // Experimental value
    3 => 0.11,
    4 => 0.16,
    5 => 0.178,
    7 => 0.2,
    8 => 0.173,
    9 => 0.142,
    10 => 0.1,
    11 => 0.03,
    13 => -0.05,
    15 => -0.21,
    17 => -0.44,
    19 => -0.54,
    // Interpolation curve
    _ => -0.158 + 0.123 * i * (1 - 0.0983 * i * (1 - 0.0195 * i)),
  };
}

double bigFontSpacingMap(double i) {
  return switch (i) {
    // Experimental value
    20 => 0.395,
    22 => 0.325,
    25 => 0.26,
    28 => 0.34,
    32 => 0.355,
    36 => 0.335,
    // Interpolation curve
    _ => ((double j) =>
            7.05 - 0.73 * i * (1 - 0.0353 * i * (1 - 0.0116 * i))
          )(min(36, i)), // Extrapolate flatly above 36
  };
}
SwiftUI code
import SwiftUI

struct ContentView: View {
    var body: some View {     
            Rectangle()
                .fill(Color.white)
                .frame(width: 400, height: 500)
                .overlay(
                    VStack {
                        ForEach([3, 4, 5, 7, 8, 9, 10, 11, 13, 15, 17, 19], id: \.self) { i in
                            Text(String(format: "CupertinoSystemText size %d", Int(i)))
                                .font(.system(size: i))
                                .foregroundColor(.black)

                        }
                        ForEach([20, 22, 25, 28, 32, 36], id: \.self) { i in
                            Text(String(format: "SystemDisplay size %d", Int(i)))
                                .font(.system(size: i))
                                .foregroundColor(.black)

                        }
                    }
                )
    }
}

#Preview {
    ContentView()
}

Related issues:

Activity

  1. dkwingsmt commented on Jun 26, 2024

    @dkwingsmt
    ContributorAuthor
  2. added
    platform-iosiOS applications specifically
    a: fidelityMatching the OEM platforms better
    p: cupertino_uicupertino_ui package in flutter/packages
    a: typographyText rendering, possibly libtxt
    on Jun 26, 2024
  3. added
    frameworkflutter/packages/flutter repository. See also f: labels.
    engineflutter/engine related. See also e: labels.
    team-iosOwned by iOS platform team
    on Jun 26, 2024
  4. jmagman commented on Jun 26, 2024

    @jmagman
    Member

    @jason-simmons do you know how the letter spacing is controlled?

  5. jason-simmons commented on Jun 26, 2024

    @jason-simmons
    Contributor

    The initial positioning of glyphs is done by HarfBuzz.

    Additional letter spacing specified by TextStyle.letterSpacing is applied by SkParagraph's Run::addSpacesEvenly.

    @Rusino

  6. Rusino commented on Jun 26, 2024

    @Rusino
    Contributor

    Yes, positioning is done by harfbuzz (and is defined by harfbuzz logic and the font metrics). The letter spacing is done by SkParagraph.

  7. added
    triaged-iosTriaged by iOS platform team
    P2Important issues not at the top of the work list
    on Jul 17, 2024
  8. makoConstruct commented on Oct 28, 2024

    @makoConstruct

    which complained about HarfBuzz's text tracking deviates from that of macOS in 2019. Although I don't quite get the content in that page and whether the issue was considered fixed.

    The harfbuzz maintainers say they decided to keep track of the issue via this chrome issue, which was marked fixed January 2020.

  9. delfme commented on Feb 27, 2025

    @delfme

    @dkwingsmt thanks for pointing me here.

    It may sound unusual, but instead of formula, it appears to be a table with values from point 6 to 96 (see attached pics)

    They disclosed values in the SF Symbol and Typography WWDC sessions and this doc
    https://developer.apple.com/design/human-interface-guidelines/typography#Specifications

    IIRC, we couldnt use those values exactly in flutter and had to fine tune them, though I might be mistaken. Additionally, the issue #120857 also affects letter spacing by increasing/reducing the space between characters. This is why you might see me sometime cross-commenting on "text-related" issues.

    Regarding the height at smaller size, we found that Apple takes a similar approach, there's no formula and the height is adjusted ad hoc to match their preferred aestethics.

    Image
    Image
    Image
    Image

  10. khaledhosny commented on Feb 28, 2025

    @khaledhosny

    It might be worth testing with HarfBuzz 10.3.0, it fixed a few issues related to letter spacing in Apple fonts with trak table.

  11. delfme commented on May 31, 2025

    @delfme

    Hi, HarfBuzz likely isn’t a factor here.
    As mentioned earlier, the difference in letter spacing also ties into the font weight issue: #120857

    Essentially, when the text renders thinner (e.g., about 0.25px thinner), it increases the perceived space between letters and words. So the final visual result is a combination of both bugs interacting at the same time. The same rationale applies when testing text fidelity in dark mode - there, the text appears 0.25px thicker, which makes the letter spacing look tighter compared to native rendering.

    So I guess #150824 and
    #120857 should be grouped into one PR, something like "Fix text rendering fidelity on iOS".

    @dkwingsmt text height is also off, and might go in the same PR. To spot that issue, please test with a multiline text.

  12. delfme commented on May 31, 2025

    @delfme

    @dkwingsmt you can also try your sample #150824 (comment) in dark mode with white text - you’ll likely see a different letter spacing, which is related to #120857.

  13. dkwingsmt commented on May 31, 2025

    @dkwingsmt
    ContributorAuthor
  14. added
    packageflutter/packages repository. See also p: labels.
    and removed
    frameworkflutter/packages/flutter repository. See also f: labels.
    on Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Important issues not at the top of the work lista: fidelityMatching the OEM platforms bettera: typographyText rendering, possibly libtxtengineflutter/engine related. See also e: labels.p: cupertino_uicupertino_ui package in flutter/packagespackageflutter/packages repository. See also p: labels.platform-iosiOS applications specificallyteam-iosOwned by iOS platform teamtriaged-iosTriaged by iOS platform team

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions