Use a custom font

Although Android and iOS offer high quality system fonts, designers want support for custom fonts. You might have a custom-built font from a designer, or perhaps you downloaded a font from Google Fonts.

A typeface is the collection of glyphs or shapes that comprise a given style of lettering. A font is one representation of that typeface at a given weight or variation. Roboto is a typeface and Roboto Bold is a font.

Flutter lets you apply a custom font across an entire app or to individual widgets. This recipe creates an app that uses custom fonts with the following steps.

1. Choose your fonts.
2. Import the font files.
3. Declare the font in the pubspec.
4. Set a font as the default.
5. Use a font in a specific widget.

You don't need to follow each step as you go. The guide offers completed example files at the end.

Your choice of font should be more than a preference. Consider which file formats work with Flutter and how the font could affect design options and app performance.

Flutter supports the following font formats:

• OpenType font collections: .ttc
• TrueType fonts: .ttf
• OpenType fonts: .otf

Flutter does not support fonts in the Web Open Font Format, .woff and .woff2, on desktop platforms.

Few sources agree on what a font file type is or which uses less space. The key difference between font file types involves how the format encodes the glyphs in the file. Most TrueType and OpenType font files have similar capabilities as they borrowed from each other as the formats and fonts improved over time.

Which font you should use depends on the following considerations.

• How much variation you need for fonts in your app?
• How much file size you can accept fonts using in your app?
• How many languages you need to support in your app?

Research what options a given font offers, like more than one weight or style per font file, variable font capability, the availability of multiple font files for a multiple font weights, or more than one width per font.

Choose the typeface or font family that meets the design needs of your app.

To work with a font, import its font files into your Flutter project.

To import font files, perform the following steps.

1. If necessary, to match the remaining steps in this guide, change the name of your Flutter app to custom_fonts.

   $ mv /path/to/my_app /path/to/custom_fonts

2. Navigate to the root of your Flutter project.

   $ cd /path/to/custom_fonts

3. Create a fonts directory at the root of your Flutter project.

   $ mkdir fonts

4. Move or copy the font files in a fonts or assets folder at the root of your Flutter project.

   $ cp ~/Downloads/*.ttf ./fonts

The resulting folder structure should resemble the following:

custom_fonts/
|- fonts/
  |- Raleway-Regular.ttf
  |- Raleway-Italic.ttf
  |- RobotoMono-Regular.ttf
  |- RobotoMono-Bold.ttf

After you've downloaded a font, include a font definition in the pubspec.yaml file. This font definition also specifies which font file should be used to render a given weight or style in your app.

To add font files to your Flutter app, complete the following steps.

1. Open the pubspec.yaml file at the root of your Flutter project.

   $ vi pubspec.yaml

2. Paste the following YAML block after the flutter declaration.

   yaml

     fonts:
       - family: Raleway
         fonts:
           - asset: fonts/Raleway-Regular.ttf
           - asset: fonts/Raleway-Italic.ttf
             style: italic
       - family: RobotoMono
         fonts:
           - asset: fonts/RobotoMono-Regular.ttf
           - asset: fonts/RobotoMono-Bold.ttf
             weight: 700

This pubspec.yaml file defines the italic style for the Raleway font family as the Raleway-Italic.ttf font file. When you set style: TextStyle(fontStyle: FontStyle.italic), Flutter swaps Raleway-Regular with Raleway-Italic.

The family value sets the name of the typeface. You use this name in the fontFamily property of a TextStyle object.

The value of an asset is a relative path from the pubspec.yaml file to the font file. These files contain the outlines for the glyphs in the font. When building the app, Flutter includes these files in the app's asset bundle.

Different typefaces implement font files in different ways. If you need a typeface with a variety of font weights and styles, choose and import font files that represent that variety.

When you import a font file that doesn't include either multiple fonts within it or variable font capabilities, don't use the style or weight property to adjust how they display. If you do use those properties on a regular font file, Flutter attempts to simulate the look. The visual result will look quite different from using the correct font file.

When you declare which font files represent styles or weights of a font, you can apply the style or weight properties.

The weight property specifies the weight of the outlines in the file as an integer multiple of 100, between 100 and 900. These values correspond to the FontWeight and can be used in the fontWeight property of a TextStyle object.

In the pubspec.yaml shown in this guide, you defined RobotoMono-Bold as the 700 weight of the font family. To use the RobotoMono-Bold font that you added to your app, set fontWeight to FontWeight.w700 in your TextStyle widget.

If hadn't added RobotoMono-Bold to your app, Flutter attempts to make the font look bold. The text then might appear to be somewhat darker.

You can't use the weight property to override the weight of the font. You can't set RobotoMono-Bold to any other weight than 700. If you set TextStyle(fontFamily: 'RobotoMono', fontWeight: FontWeight.w900), the displayed font would still render as however bold RobotoMono-Bold looks.

The style property specifies whether the glyphs in the font file display as either italic or normal. These values correspond to the FontStyle. You can use these styles in the fontStyle property of a TextStyle object.

In the pubspec.yaml shown in this guide, you defined Raleway-Italic as being in the italic style. To use the Raleway-Italic font that you added to your app, set style: TextStyle(fontStyle: FontStyle.italic). Flutter swaps Raleway-Regular with Raleway-Italic when rendering.

If hadn't added Raleway-Italic to your app, Flutter attempts to make the font look italic. The text then might appear to be leaning to the right.

You can't use the style property to override the glyphs of a font. If you set TextStyle(fontFamily: 'Raleway', fontStyle: FontStyle.normal), the displayed font would still render as italic. The regular style of an italic font is italic.

To apply a font to text, you can set the font as the app's default font in its theme.

To set a default font, set the fontFamily property in the app's theme. Match the fontFamily value to the family name declared in the pubspec.yaml file.

The result would resemble the following code.

return MaterialApp(
  title: 'Custom Fonts',
  // Set Raleway as the default app font.
  theme: ThemeData(fontFamily: 'Raleway'),
  home: const MyHomePage(),
);

To learn more about themes, check out the Using Themes to share colors and font styles recipe.

To apply the font to a specific widget like a Text widget, provide a TextStyle to the widget.

For this guide, try to apply the RobotoMono font to a single Text widget. Match the fontFamily value to the family name declared in the pubspec.yaml file.

The result would resemble the following code.

child: Text(
  'Roboto Mono sample',
  style: TextStyle(fontFamily: 'RobotoMono'),
),

Download the Raleway and RobotoMono font files from Google Fonts.

1. Open the pubspec.yaml file at the root of your Flutter project.

   $ vi pubspec.yaml

2. Replace its contents with the following YAML.

   yaml

   name: custom_fonts
   description: An example of how to use custom fonts with Flutter
   
   dependencies:
     flutter:
       sdk: flutter
   
   dev_dependencies:
     flutter_test:
       sdk: flutter
   
   flutter:
     fonts:
       - family: Raleway
         fonts:
           - asset: fonts/Raleway-Regular.ttf
           - asset: fonts/Raleway-Italic.ttf
             style: italic
       - family: RobotoMono
         fonts:
           - asset: fonts/RobotoMono-Regular.ttf
           - asset: fonts/RobotoMono-Bold.ttf
             weight: 700
     uses-material-design: true

1. Open the main.dart file in the lib/ directory of your Flutter project.

   $ vi lib/main.dart

2. Replace its contents with the following Dart code.

   dart

   import 'package:flutter/material.dart';
   
   void main() => runApp(const MyApp());
   
   class MyApp extends StatelessWidget {
     const MyApp({super.key});
   
     @override
     Widget build(BuildContext context) {
       return MaterialApp(
         title: 'Custom Fonts',
         // Set Raleway as the default app font.
         theme: ThemeData(fontFamily: 'Raleway'),
         home: const MyHomePage(),
       );
     }
   }
   
   class MyHomePage extends StatelessWidget {
     const MyHomePage({super.key});
   
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         // The AppBar uses the app-default Raleway font.
         appBar: AppBar(title: const Text('Custom Fonts')),
         body: const Center(
           // This Text widget uses the RobotoMono font.
           child: Text(
             'Roboto Mono sample',
             style: TextStyle(fontFamily: 'RobotoMono'),
           ),
         ),
       );
     }
   }

The resulting Flutter app should display the following screen.