diff --git a/content/develop/concepts/configuration/theming-fonts.md b/content/develop/concepts/configuration/theming-fonts.md index 6fc622a5c..9e908cef7 100644 --- a/content/develop/concepts/configuration/theming-fonts.md +++ b/content/develop/concepts/configuration/theming-fonts.md @@ -118,7 +118,7 @@ project_directory/ ### Example 2: Define an alternative font with static font files -In this configuration example, an alternative font is declared with multiple static font files. For each font, four static files define the following weight-style pairs: +In this configuration example, an alternative font is declared with multiple static font files. To cover basic Markdown formatting, each font should have at least four static files to define the following weight-style pairs: - normal normal - normal bold @@ -184,21 +184,33 @@ If you configure your app to include any third-party integrations, including ext -In your configuration file, wherever you declare a default font, you can use a comma-separated list of fonts instead. You can always include one of Streamlit's default fonts as a final fallback. +In your configuration file, wherever you declare a default font, you can use a comma-separated list of fonts instead. The font (or comma-separated list of fonts) is passed to the CSS [`font-family`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) property. -- To specify a fallback font in Example 1, in `.streamlit/config.toml`, change the `[theme]` table to the following text: +You can always include one of Streamlit's default fonts as a final fallback. The following example uses [Nunito](https://fonts.google.com/specimen/Nunito) font. The configuration file points to the Google-hosted font files and identifies Streamlit's built-in font as the backup. - ```toml - [theme] - font="noto-sans, sans-serif" - codeFont="noto-mono, monospace" - ``` +A line-by-line explanation of this example is available in a [tutorial](/develop/tutorials/configuration-and-theming/external-fonts). - This is the same configuration as in Example 1 except that Source Sans and Source Mono are declared as fallback fonts. You can define more than one fallback. When you declare a default font, the font (or comma-separated list of fonts) is passed to the CSS [`font-family`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) property. +`.streamlit/config.toml`: + +```toml +[[theme.fontFaces]] +family="Nunito" +url="https://fonts.gstatic.com/s/nunito/v31/XRXX3I6Li01BKofIMNaDRs7nczIH.woff2" +style="italic" +weight="200 1000" +[[theme.fontFaces]] +family="Nunito" +url="https://fonts.gstatic.com/s/nunito/v31/XRXV3I6Li01BKofINeaBTMnFcQ.woff2" +style="normal" +weight="200 1000" + +[theme] +font="Nunito, sans-serif" +``` -If any of your font family names contain spaces and you are declaring a fallback sequence, use inner quotes around the names. For example, if you name the font `"Noto Sans"`, use `font="'Noto Sans', sans-serif"` instead. +If any of your font family names contain spaces and you are declaring a fallback sequence, use inner quotes around the names. For example, if you name the font `"Nunito Sans"`, use `font="'Nunito Sans', sans-serif"` instead. diff --git a/content/develop/tutorials/theming/_index.md b/content/develop/tutorials/theming/_index.md index ae23813e3..9f7769d98 100644 --- a/content/develop/tutorials/theming/_index.md +++ b/content/develop/tutorials/theming/_index.md @@ -7,6 +7,14 @@ slug: /develop/tutorials/configuration-and-theming + + +
Use external font files and fallbacks to customize your font
+ +Make a new font available to your app. This tutorial uses externally hosted font files to define an alternative font and declares a built-in fallback. + + +
Use static font files to customize your font
diff --git a/content/develop/tutorials/theming/external-fonts.md b/content/develop/tutorials/theming/external-fonts.md new file mode 100644 index 000000000..70e6c7723 --- /dev/null +++ b/content/develop/tutorials/theming/external-fonts.md @@ -0,0 +1,252 @@ +--- +title: Use externally hosted fonts and fallbacks to customize your font +slug: /develop/tutorials/configuration-and-theming/external-fonts +description: Learn how to load an alternative font and use it in your app. +--- + +# Use externally hosted fonts and fallbacks to customize your font + +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). + +## Prerequisites + +- This tutorial requires the following version of Streamlit: + + ```text + streamlit>=1.46.0 + ``` + +- You should have a clean working directory called `your-repository`. +- 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. + +## Summary + +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. + +Here's a look at what you'll build: + + + +Directory structure: + +```none +your_repository/ +├── .streamlit/ +│ └── config.toml +└── streamlit_app.py +``` + +`.streamlit/config.toml`: + +```toml +[[theme.fontFaces]] +family="Nunito" +url="https://fonts.gstatic.com/s/nunito/v31/XRXX3I6Li01BKofIMNaDRs7nczIH.woff2" +style="italic" +weight="200 1000" +[[theme.fontFaces]] +family="Nunito" +url="https://fonts.gstatic.com/s/nunito/v31/XRXV3I6Li01BKofINeaBTMnFcQ.woff2" +style="normal" +weight="200 1000" +[[theme.fontFaces]] +family="Space Mono" +url="https://fonts.gstatic.com/s/spacemono/v17/i7dNIFZifjKcF5UAWdDRYERMR3K_MQacbw.woff2" +style="italic" +weight="400" +[[theme.fontFaces]] +family="Space Mono" +url="https://fonts.gstatic.com/s/spacemono/v17/i7dPIFZifjKcF5UAWdDRYEF8RXi4EwQ.woff2" +style="normal" +weight="400" +[[theme.fontFaces]] +family="Space Mono" +url="https://fonts.gstatic.com/s/spacemono/v17/i7dSIFZifjKcF5UAWdDRYERE_FeqHCSRRXaPYw.woff2" +style="italic" +weight="700" +[[theme.fontFaces]] +family="Space Mono" +url="https://fonts.gstatic.com/s/spacemono/v17/i7dMIFZifjKcF5UAWdDRaPpZUFWaHi6WZ3Q.woff2" +style="normal" +weight="700" + +[theme] +font="Nunito, sans-serif" +codeFont="'Space Mono', monospace" +``` + +`streamlit_app.py`: + +``` +import streamlit as st + +st.write("Normal efg") +st.write("*Italic efg*") +st.write("**Bold efg**") +st.write("***Bold-italic efg***") +st.write("`Code normal efg`") +st.write("*`Code italic efg`*") +st.write("**`Code bold efg`**") +st.write("***`Code bold-italic efg`***") +``` + + + +## Collect your font file URLs + +1. Go to [Google fonts](https://fonts.google.com/). + +1. Search for or follow the link to [Nunito](https://fonts.google.com/specimen/Nunito), and select "**Get font**." + +1. Search for or follow the link to [Space Mono](https://fonts.google.com/specimen/Space+Mono), and select "**Get font**." + +1. To get a link to a style sheet for your font files, in the upper-right corner, select the shopping bag (shopping_bag), and then select "code **Get embed code**." + +1. On the right, in the first code block, copy the `href` URL from the third link, and paste it into a new tab. + + 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: + + ```none + 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 + ``` + +1. Go to your new tab and visit the URL. + + This page is a style sheet. It is filled with font-face declarations that look like the following text: + + ```css + /* cyrillic-ext */ + @font-face { + font-family: "Nunito"; + font-style: italic; + font-weight: 200 1000; + font-display: swap; + src: url(https://fonts.gstatic.com/s/nunito/v31/XRXX3I6Li01BKofIMNaORs7nczIHNHI.woff2) + format("woff2"); + unicode-range: + U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F; + } + ``` + + 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. + +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. + +## Create your app configuration + +1. In `your_repository/`, create a `.streamlit/config.toml` file: + + ```none + your_repository/ + └── .streamlit/ + └── config.toml + ``` + +1. To define your alternative fonts, in `.streamlit/config.toml`, paste each `@font-face` declaration, and change each one into a `[[theme.fontFaces]]` table. + + The following values in each `@font-face` declaration become the indicated value in a `[[theme.fontFaces]]` table: + - `font-family` → `family` + - `src: url` → `url` (Ignore `format`, and just keep the URL.) + - `font-style` → `style` + - `font-weight` → `weight` + - Optional: `unicode-range` → `unicodeRange` (This is only useful if you are using more than basic latin sets.) + + 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: + + ```toml + [[theme.fontFaces]] + family="Nunito" + url="https://fonts.gstatic.com/s/nunito/v31/XRXX3I6Li01BKofIMNaDRs7nczIH.woff2" + style="italic" + weight="200 1000" + [[theme.fontFaces]] + family="Nunito" + url="https://fonts.gstatic.com/s/nunito/v31/XRXV3I6Li01BKofINeaBTMnFcQ.woff2" + style="normal" + weight="200 1000" + [[theme.fontFaces]] + family="Space Mono" + url="https://fonts.gstatic.com/s/spacemono/v17/i7dNIFZifjKcF5UAWdDRYERMR3K_MQacbw.woff2" + style="italic" + weight="400" + [[theme.fontFaces]] + family="Space Mono" + url="https://fonts.gstatic.com/s/spacemono/v17/i7dPIFZifjKcF5UAWdDRYEF8RXi4EwQ.woff2" + style="normal" + weight="400" + [[theme.fontFaces]] + family="Space Mono" + url="https://fonts.gstatic.com/s/spacemono/v17/i7dSIFZifjKcF5UAWdDRYERE_FeqHCSRRXaPYw.woff2" + style="italic" + weight="700" + [[theme.fontFaces]] + family="Space Mono" + url="https://fonts.gstatic.com/s/spacemono/v17/i7dMIFZifjKcF5UAWdDRaPpZUFWaHi6WZ3Q.woff2" + style="normal" + weight="700" + ``` + + 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. + +1. To set your alternative fonts as the default font for your app, in `.streamlit/config.toml`, add the following text: + + ```toml + [theme] + font="Nunito, sans-serif" + codeFont="'Space Mono', monospace" + ``` + + 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. + +## Build the example + +To verify that your font is loaded correctly, create a simple app. + +### Initialize your app + +1. In your_repository, create a file named `streamlit_app.py`. + +1. In a terminal, change directories to your_repository, and start your app: + + ```bash + streamlit run streamlit_app.py + ``` + + Your app will be blank because you still need to add code. + +1. In `streamlit_app.py`, write the following: + + ``` + import streamlit as st + ``` + +1. Save your `streamlit_app.py` file, and view your running app. + +1. In your app, select "**Always rerun**", or press the "**A**" key. + + Your preview will be blank but will automatically update as you save changes to `streamlit_app.py`. + +1. Return to your code. + +### Display some text in your app + +1. Create a `streamlit_app.py` file in your working directory. + +1. In `streamlit_app.py`, add the following text: + + ``` + import streamlit as st + + st.write("Normal efg") + st.write("*Italic efg*") + st.write("**Bold efg**") + st.write("***Bold-italic efg***") + st.write("`Code normal efg`") + st.write("*`Code italic efg`*") + st.write("**`Code bold efg`**") + st.write("***`Code bold-italic efg`***") + ``` + + 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." + +1. Save your `streamlit_app.py` file, and view your running app. diff --git a/content/develop/tutorials/theming/static-fonts.md b/content/develop/tutorials/theming/static-fonts.md index 358e77a28..871d69340 100644 --- a/content/develop/tutorials/theming/static-fonts.md +++ b/content/develop/tutorials/theming/static-fonts.md @@ -84,8 +84,8 @@ font="tuffy" import streamlit as st st.write("Normal ABCabc123") -st.write("_Italic ABCabc123_") -st.write("*Bold ABCabc123*") +st.write("*Italic ABCabc123*") +st.write("**Bold ABCabc123**") st.write("***Bold-italic ABCabc123***") st.write("`Code ABCabc123`") ``` @@ -202,7 +202,7 @@ To verify that your font is loaded correctly, create a simple app. 1. In a terminal, change directories to your_repository, and start your app: ```bash - streamlit run app.py + streamlit run streamlit_app.py ``` Your app will be blank because you still need to add code. @@ -231,8 +231,8 @@ To verify that your font is loaded correctly, create a simple app. import streamlit as st st.write("Normal ABCabc123") - st.write("_Italic ABCabc123_") - st.write("*Bold ABCabc123*") + st.write("*Italic ABCabc123*") + st.write("**Bold ABCabc123**") st.write("***Bold-italic ABCabc123***") st.write("`Code ABCabc123`") ``` diff --git a/content/develop/tutorials/theming/variable-fonts.md b/content/develop/tutorials/theming/variable-fonts.md index 0ef06001f..fa7239ed0 100644 --- a/content/develop/tutorials/theming/variable-fonts.md +++ b/content/develop/tutorials/theming/variable-fonts.md @@ -70,10 +70,13 @@ codeFont="noto-mono" import streamlit as st st.write("Normal efg") -st.write("_Italic efg_") -st.write("*Bold efg*") +st.write("*Italic efg*") +st.write("**Bold efg**") st.write("***Bold-italic efg***") -st.write("`Code efg`") +st.write("`Code normal efg`") +st.write("*`Code italic efg`*") +st.write("**`Code bold efg`**") +st.write("***`Code bold-italic efg`***") ``` @@ -183,7 +186,7 @@ To verify that your font is loaded correctly, create a simple app. 1. In a terminal, change directories to your_repository, and start your app: ```bash - streamlit run app.py + streamlit run streamlit_app.py ``` Your app will be blank because you still need to add code. @@ -212,10 +215,13 @@ To verify that your font is loaded correctly, create a simple app. import streamlit as st st.write("Normal efg") - st.write("_Italic efg_") - st.write("*Bold efg*") + st.write("*Italic efg*") + st.write("**Bold efg**") st.write("***Bold-italic efg***") - st.write("`Code efg`") + st.write("`Code normal efg`") + st.write("*`Code italic efg`*") + st.write("**`Code bold efg`**") + st.write("***`Code bold-italic efg`***") ``` The example includes "efg" in each line to better show the typographical differences when you run your app. The italic "f" descends below baseline, but the normal "f" doesn't. The italic "e" has a rounded front, but the normal "e" has a sharp corner. diff --git a/content/menu.md b/content/menu.md index 9f77d5953..36bec911c 100644 --- a/content/menu.md +++ b/content/menu.md @@ -678,6 +678,8 @@ site_menu: url: /develop/tutorials/chat-and-llm-apps/validate-and-edit-chat-responses - category: Develop / Tutorials / Configuration and theming url: /develop/tutorials/configuration-and-theming + - category: Develop / Tutorials / Configuration and theming / Use external font files + url: /develop/tutorials/configuration-and-theming/external-fonts - category: Develop / Tutorials / Configuration and theming / Use static font files url: /develop/tutorials/configuration-and-theming/static-fonts - category: Develop / Tutorials / Configuration and theming / Use variable font files