|
| 1 | +--- |
| 2 | +title: Use externally hosted fonts and fallbacks to customize your font |
| 3 | +slug: /develop/tutorials/configuration-and-theming/external-fonts |
| 4 | +description: Learn how to load an alternative font and use it in your app. |
| 5 | +--- |
| 6 | + |
| 7 | +# Use externally hosted fonts and fallbacks to customize your font |
| 8 | + |
| 9 | +Streamlit comes with Source Sans as the default font, but you can configure your app to use another font. This tutorial uses variable font files and is a walkthrough of Example 3 from [Customize fonts in your Streamlit app](/develop/concepts/configuration/theming-customize-fonts#example-1-define-an-alternative-font-with-variable-font-files). For an example that uses self-hosted variable font files, see [Use variable font files to customize your font](/develop/tutorials/configuration-and-theming/variable-fonts). For an example that uses self-hosted static font files, see [Use static font files to customize your font](/develop/tutorials/configuration-and-theming/static-fonts). |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +- This tutorial requires the following version of Streamlit: |
| 14 | + |
| 15 | + ```text |
| 16 | + streamlit>=1.46.0 |
| 17 | + ``` |
| 18 | + |
| 19 | +- You should have a clean working directory called `your-repository`. |
| 20 | +- You should have a basic understanding of working with font files in web development. Otherwise, start by reading [Customize fonts in your Streamlit app](/develop/concepts/configuration/theming-customize-fonts) up to Example 3. |
| 21 | + |
| 22 | +## Summary |
| 23 | + |
| 24 | +The following example uses a Google-hosted instances of [Nunito](https://fonts.google.com/specimen/Nunito) and [Space Mono](https://fonts.google.com/specimen/Space+Mono). Nunito is defined in variable font files. However, because font style is not parameterized, Nunito requires two files to define the normal and italic styles separately. Space Mono is defined in static font files. |
| 25 | + |
| 26 | +Here's a look at what you'll build: |
| 27 | + |
| 28 | +<Collapse title="Complete config.toml file" expanded={false}> |
| 29 | + |
| 30 | +Directory structure: |
| 31 | + |
| 32 | +```none |
| 33 | +your_repository/ |
| 34 | +├── .streamlit/ |
| 35 | +│ └── config.toml |
| 36 | +└── streamlit_app.py |
| 37 | +``` |
| 38 | + |
| 39 | +`.streamlit/config.toml`: |
| 40 | + |
| 41 | +```toml |
| 42 | +[[theme.fontFaces]] |
| 43 | +family="Nunito" |
| 44 | +url="https://fonts.gstatic.com/s/nunito/v31/XRXX3I6Li01BKofIMNaDRs7nczIH.woff2" |
| 45 | +style="italic" |
| 46 | +weight="200 1000" |
| 47 | +[[theme.fontFaces]] |
| 48 | +family="Nunito" |
| 49 | +url="https://fonts.gstatic.com/s/nunito/v31/XRXV3I6Li01BKofINeaBTMnFcQ.woff2" |
| 50 | +style="normal" |
| 51 | +weight="200 1000" |
| 52 | +[[theme.fontFaces]] |
| 53 | +family="Space Mono" |
| 54 | +url="https://fonts.gstatic.com/s/spacemono/v17/i7dNIFZifjKcF5UAWdDRYERMR3K_MQacbw.woff2" |
| 55 | +style="italic" |
| 56 | +weight="400" |
| 57 | +[[theme.fontFaces]] |
| 58 | +family="Space Mono" |
| 59 | +url="https://fonts.gstatic.com/s/spacemono/v17/i7dPIFZifjKcF5UAWdDRYEF8RXi4EwQ.woff2" |
| 60 | +style="normal" |
| 61 | +weight="400" |
| 62 | +[[theme.fontFaces]] |
| 63 | +family="Space Mono" |
| 64 | +url="https://fonts.gstatic.com/s/spacemono/v17/i7dSIFZifjKcF5UAWdDRYERE_FeqHCSRRXaPYw.woff2" |
| 65 | +style="italic" |
| 66 | +weight="700" |
| 67 | +[[theme.fontFaces]] |
| 68 | +family="Space Mono" |
| 69 | +url="https://fonts.gstatic.com/s/spacemono/v17/i7dMIFZifjKcF5UAWdDRaPpZUFWaHi6WZ3Q.woff2" |
| 70 | +style="normal" |
| 71 | +weight="700" |
| 72 | + |
| 73 | +[theme] |
| 74 | +font="Nunito, sans-serif" |
| 75 | +codeFont="'Space Mono', monospace" |
| 76 | +``` |
| 77 | + |
| 78 | +`streamlit_app.py`: |
| 79 | + |
| 80 | +``` |
| 81 | +import streamlit as st |
| 82 | +
|
| 83 | +st.write("Normal efg") |
| 84 | +st.write("*Italic efg*") |
| 85 | +st.write("**Bold efg**") |
| 86 | +st.write("***Bold-italic efg***") |
| 87 | +st.write("`Code normal efg`") |
| 88 | +st.write("*`Code italic efg`*") |
| 89 | +st.write("**`Code bold efg`**") |
| 90 | +st.write("***`Code bold-italic efg`***") |
| 91 | +``` |
| 92 | + |
| 93 | +</Collapse> |
| 94 | + |
| 95 | +## Collect your font file URLs |
| 96 | + |
| 97 | +1. Go to [Google fonts](https://fonts.google.com/). |
| 98 | + |
| 99 | +1. Search for or follow the link to [Nunito](https://fonts.google.com/specimen/Nunito), and select "**Get font**." |
| 100 | + |
| 101 | +1. Search for or follow the link to [Space Mono](https://fonts.google.com/specimen/Space+Mono), and select "**Get font**." |
| 102 | + |
| 103 | +1. To get a link to a style sheet for your font files, in the upper-right corner, select the shopping bag (<i style={{ verticalAlign: "-.25em" }} className={{ class: "material-icons-sharp" }}>shopping_bag</i>), and then select "<i style={{ verticalAlign: "-.25em" }} className={{ class: "material-icons-sharp" }}>code</i> **Get embed code**." |
| 104 | + |
| 105 | +1. On the right, in the first code block, copy the `href` URL from the third link, and paste it into a new tab. |
| 106 | + |
| 107 | + By default, the "Embed Code" page loads with the "Web" tab and "<link>" radio option selected. The first code block is titled, "Embed code in the <head> of your html." The URL is a link to a style sheet and should look like the following text: |
| 108 | + |
| 109 | + ```none |
| 110 | + https://fonts.googleapis.com/css2?family=Nunito:ital,wght@0,200..1000;1,200..1000&family=Space+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap |
| 111 | + ``` |
| 112 | + |
| 113 | +1. Go to your new tab and visit the URL. |
| 114 | + |
| 115 | + This page is a style sheet. It is filled with font-face declarations that look like the following text: |
| 116 | + |
| 117 | + ```css |
| 118 | + /* cyrillic-ext */ |
| 119 | + @font-face { |
| 120 | + font-family: "Nunito"; |
| 121 | + font-style: italic; |
| 122 | + font-weight: 200 1000; |
| 123 | + font-display: swap; |
| 124 | + src: url(https://fonts.gstatic.com/s/nunito/v31/XRXX3I6Li01BKofIMNaORs7nczIHNHI.woff2) |
| 125 | + format("woff2"); |
| 126 | + unicode-range: |
| 127 | + U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F; |
| 128 | + } |
| 129 | + ``` |
| 130 | + |
| 131 | + Each font-face declaration starts with a comment to indication which character set is included in that declaration. For most English apps, only the `/* latin */` declarations are needed. |
| 132 | + |
| 133 | +1. To store the portion of the style sheet you'll need in later steps, copy the font-face declarations that are prefixed with the `/* latin */` comment, and paste them into a text file. |
| 134 | + |
| 135 | +## Create your app configuration |
| 136 | + |
| 137 | +1. In `your_repository/`, create a `.streamlit/config.toml` file: |
| 138 | + |
| 139 | + ```none |
| 140 | + your_repository/ |
| 141 | + └── .streamlit/ |
| 142 | + └── config.toml |
| 143 | + ``` |
| 144 | + |
| 145 | +1. To define your alternative fonts, in `.streamlit/config.toml`, paste each `@font-face` declaration, and change each one into a `[[theme.fontFaces]]` table. |
| 146 | + |
| 147 | + The following values in each `@font-face` declaration become the indicated value in a `[[theme.fontFaces]]` table: |
| 148 | + - `font-family` → `family` |
| 149 | + - `src: url` → `url` (Ignore `format`, and just keep the URL.) |
| 150 | + - `font-style` → `style` |
| 151 | + - `font-weight` → `weight` |
| 152 | + - Optional: `unicode-range` → `unicodeRange` (This is only useful if you are using more than basic latin sets.) |
| 153 | + |
| 154 | + Remember to remove the comment lines and CSS syntax characters, which aren't compatible with TOML files. Your configuration file should contain the following text: |
| 155 | + |
| 156 | + ```toml |
| 157 | + [[theme.fontFaces]] |
| 158 | + family="Nunito" |
| 159 | + url="https://fonts.gstatic.com/s/nunito/v31/XRXX3I6Li01BKofIMNaDRs7nczIH.woff2" |
| 160 | + style="italic" |
| 161 | + weight="200 1000" |
| 162 | + [[theme.fontFaces]] |
| 163 | + family="Nunito" |
| 164 | + url="https://fonts.gstatic.com/s/nunito/v31/XRXV3I6Li01BKofINeaBTMnFcQ.woff2" |
| 165 | + style="normal" |
| 166 | + weight="200 1000" |
| 167 | + [[theme.fontFaces]] |
| 168 | + family="Space Mono" |
| 169 | + url="https://fonts.gstatic.com/s/spacemono/v17/i7dNIFZifjKcF5UAWdDRYERMR3K_MQacbw.woff2" |
| 170 | + style="italic" |
| 171 | + weight="400" |
| 172 | + [[theme.fontFaces]] |
| 173 | + family="Space Mono" |
| 174 | + url="https://fonts.gstatic.com/s/spacemono/v17/i7dPIFZifjKcF5UAWdDRYEF8RXi4EwQ.woff2" |
| 175 | + style="normal" |
| 176 | + weight="400" |
| 177 | + [[theme.fontFaces]] |
| 178 | + family="Space Mono" |
| 179 | + url="https://fonts.gstatic.com/s/spacemono/v17/i7dSIFZifjKcF5UAWdDRYERE_FeqHCSRRXaPYw.woff2" |
| 180 | + style="italic" |
| 181 | + weight="700" |
| 182 | + [[theme.fontFaces]] |
| 183 | + family="Space Mono" |
| 184 | + url="https://fonts.gstatic.com/s/spacemono/v17/i7dMIFZifjKcF5UAWdDRaPpZUFWaHi6WZ3Q.woff2" |
| 185 | + style="normal" |
| 186 | + weight="700" |
| 187 | + ``` |
| 188 | + |
| 189 | + The `[[theme.fontFaces]]` table can be repeated to use multiple files to define a single font or to define multiple fonts. In this example, the definitions make `"Nunito"` and `"Space Mono"` available to other font configuration options. |
| 190 | + |
| 191 | +1. To set your alternative fonts as the default font for your app, in `.streamlit/config.toml`, add the following text: |
| 192 | + |
| 193 | + ```toml |
| 194 | + [theme] |
| 195 | + font="Nunito, sans-serif" |
| 196 | + codeFont="'Space Mono', monospace" |
| 197 | + ``` |
| 198 | + |
| 199 | + This sets Nunito as the default for all text in your app except inline code and code blocks, which will be Space Mono instead. If Google's font service is unavailable, the app will fall back to the indicated built-in fonts. Because there is a space in "Space Mono", the configuration option needs an inner quote on that family. If you want to avoid inner quotes, you can use hyphens or underscores in your font family declarations. |
| 200 | + |
| 201 | +## Build the example |
| 202 | + |
| 203 | +To verify that your font is loaded correctly, create a simple app. |
| 204 | + |
| 205 | +### Initialize your app |
| 206 | + |
| 207 | +1. In your_repository, create a file named `streamlit_app.py`. |
| 208 | + |
| 209 | +1. In a terminal, change directories to your_repository, and start your app: |
| 210 | + |
| 211 | + ```bash |
| 212 | + streamlit run streamlit_app.py |
| 213 | + ``` |
| 214 | + |
| 215 | + Your app will be blank because you still need to add code. |
| 216 | + |
| 217 | +1. In `streamlit_app.py`, write the following: |
| 218 | + |
| 219 | + ``` |
| 220 | + import streamlit as st |
| 221 | + ``` |
| 222 | + |
| 223 | +1. Save your `streamlit_app.py` file, and view your running app. |
| 224 | + |
| 225 | +1. In your app, select "**Always rerun**", or press the "**A**" key. |
| 226 | + |
| 227 | + Your preview will be blank but will automatically update as you save changes to `streamlit_app.py`. |
| 228 | + |
| 229 | +1. Return to your code. |
| 230 | + |
| 231 | +### Display some text in your app |
| 232 | + |
| 233 | +1. Create a `streamlit_app.py` file in your working directory. |
| 234 | + |
| 235 | +1. In `streamlit_app.py`, add the following text: |
| 236 | + |
| 237 | + ``` |
| 238 | + import streamlit as st |
| 239 | +
|
| 240 | + st.write("Normal efg") |
| 241 | + st.write("*Italic efg*") |
| 242 | + st.write("**Bold efg**") |
| 243 | + st.write("***Bold-italic efg***") |
| 244 | + st.write("`Code normal efg`") |
| 245 | + st.write("*`Code italic efg`*") |
| 246 | + st.write("**`Code bold efg`**") |
| 247 | + st.write("***`Code bold-italic efg`***") |
| 248 | + ``` |
| 249 | + |
| 250 | + The example includes "efg" in each line to better show the typographical differences when you run your app. In Space Mono, the italic "f" descends below baseline, but the normal "f" doesn't. Space Mono also has different serifs on its normal and italic "l." |
| 251 | + |
| 252 | +1. Save your `streamlit_app.py` file, and view your running app. |
0 commit comments