Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update font optimization page #42266

Merged
merged 7 commits into from
Nov 2, 2022
Merged

update font optimization page #42266

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
989954d
update font optimization page
ismaelrumzan Oct 31, 2022
71c4a97
updated api ref fonts to use /pages
ismaelrumzan Oct 31, 2022
8424e63
Merge branch 'canary' into v13-docs-fonts-update
ismaelrumzan Oct 31, 2022
d158823
Merge branch 'canary' into v13-docs-fonts-update
delbaoliveira Nov 1, 2022
7838cd4
Update docs/basic-features/font-optimization.md
timneutkens Nov 2, 2022
49e5b38
Merge branch 'canary' into v13-docs-fonts-update
delbaoliveira Nov 2, 2022
f770565
Update docs/basic-features/font-optimization.md
delbaoliveira Nov 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/api-reference/next/font.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,14 +107,14 @@ For usage, review [Local Fonts](/docs/optimizing/fonts#local-fonts).

### `src`

The path of the font file as a string relative to the directory where the font loader function is called or to the `app` directory.
The path of the font file as a string relative to the directory where the font loader function is called or to the `pages` directory.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The path of the font file as a string relative to the directory where the font loader function is called.

This is correct

or to the pages directory.

It's always relative to where it's called.


- Required

Examples are:

- `'./fonts/my-font.woff2'` where `my-font.woff2` is placed in a directory named `fonts` inside the `app` directory
- if the font loader function is called in `app/page.tsx` using `'../styles/fonts/my-font.ttf'`, then `my-font.ttf` is placed in `styles/fonts` at the root of the project
- `'./fonts/my-font.woff2'` where `my-font.woff2` is placed in a directory named `fonts` inside the `pages` directory
- if the font loader function is called in `pages/index.js` using `'../styles/fonts/my-font.ttf'`, then `my-font.ttf` is placed in `styles/fonts` at the root of the project

### `weight`

Expand Down Expand Up @@ -194,8 +194,8 @@ If you would like to set your styles in an external style sheet and specify addi

In addition to importing the font, also import the CSS file where the CSS variable is defined and set the variable option of the font loader object as follows:

```tsx
// app/page.tsx
```js
// pages/index.js
import { Inter } from '@next/font/google'
import styles from '../styles/component.module.css'

Expand All @@ -206,8 +206,8 @@ const inter = Inter({

To use the font, set the `className` of the parent container of the text you would like to style to the font loader's `variable` value and the `className` of the text to the `styles` property from the external CSS file.

```tsx
// app/page.tsx
```js
// pages/index.js
<main className={inter.variable}>
<p className={styles.text}>Hello World</p>
</main>
Expand Down
108 changes: 67 additions & 41 deletions docs/basic-features/font-optimization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,49 +26,82 @@ Automatically self-host any Google Font. Fonts are included in the deployment an

Import the font you would like to use from `@next/font/google` as a function. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.

```jsx
// app/layout.tsx
import { Inter } from '@next/font/google'
To use the font in all your pages, add it to [`_app.js` file](https://nextjs.org/docs/advanced-features/custom-app) under `/pages` as shown below:

```js:pages/_app.js
import { Inter } from '@next/font/google';

// If loading a variable font, you don't need to specify the font weight
const inter = Inter()

export default function RootLayout({
children,
}: {
children: React.ReactNode,
}) {
export default function MyApp({ Component, pageProps }) {
return (
<html lang="en" className={inter.className}>
<body>{children}</body>
</html>
<main className={inter.className}>
<Component {...pageProps} />
</main>
)
}
```

If you can't use a variable font, you will **need to specify a weight**:

```jsx
// app/layout.tsx
import { Roboto } from '@next/font/google'
```js:pages/_app.js
import { Roboto } from '@next/font/google';

const roboto = Roboto({
weight: '400',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing multiple weights/styles in API reference for both google and local.

})

export default function RootLayout({
children,
}: {
children: React.ReactNode,
}) {
export default function MyApp({ Component, pageProps }) {
return (
<main className={roboto.className}>
<Component {...pageProps} />
</main>
)
}
```

#### Apply the font in `<head>`

You can also use the font without a wrapper and `className` by injecting it inside the `<head>` as follows:

```js:pages/_app.js
import { Inter } from '@next/font/google';

const inter = Inter();

export default function MyApp({ Component, pageProps }) {
return (
<html lang="en" className={roboto.className}>
<body>{children}</body>
</html>
<>
<style jsx global>{`
html {
font-family: ${inter.style.fontFamily};
}
`}</style>
<Component {...pageProps} />
</>
)
}
```

#### Single page usage

To use the font on a single page, add it to the specific page as shown below:

```js:pages/index.js
import { Inter } from '@next/font/google';

const inter = Inter();

export default function Home() {
return (
<div className={inter.className}>
<p>Hello World</p>
</div>
);
}
```

#### Specifying a subset

Google Fonts are automatically [subset](https://fonts.google.com/knowledge/glossary/subsetting). This reduces the size of the font file and improves performance. You'll need to define which of these subsets you want to preload. Failing to specify any subsets while [`preload`](/docs/api-reference/next/font.md#preload) is true will result in a warning.
Expand All @@ -77,9 +110,8 @@ This can be done in 2 ways:

- On a font per font basis by adding it to the function call

```tsx
// app/layout.tsx
const inter = Inter({ subsets: ['latin'] })
```js:pages/_app.js
const inter = Inter({ subsets: ["latin"] });
```

- Globally for all your fonts in your `next.config.js`
Expand All @@ -103,22 +135,17 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontgoogle) f

Import `@next/font/local` and specify the `src` of your local font file. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.

```jsx
/// app/layout.tsx
import localFont from '@next/font/local'
```js:pages/_app.js
import localFont from '@next/font/local';

// Font files can be colocated inside of `app`
const myFont = localFont({ src: './my-font.woff2' })
// Font files can be colocated inside of `pages`
const myFont = localFont({ src: './my-font.woff2' });

export default function RootLayout({
children,
}: {
children: React.ReactNode,
}) {
export default function MyApp({ Component, pageProps }) {
return (
<html lang="en" className={myFont.className}>
<body>{children}</body>
</html>
<main className={myFont.className}>
<Component {...pageProps} />
</main>
)
}
```
Expand All @@ -129,9 +156,8 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontlocal) fo

When a font function is called on a page of your site, it is not globally available and preloaded on all routes. Rather, the font is only preloaded on the related route/s based on the type of file where it is used:

- if it's a [unique page](https://beta.nextjs.org/docs/routing/pages-and-layouts#pages), it is preloaded on the unique route for that page
- if it's a [layout](https://beta.nextjs.org/docs/routing/pages-and-layouts#layouts), it is preloaded on all the routes wrapped by the layout
- if it's the [root layout](https://beta.nextjs.org/docs/routing/pages-and-layouts#root-layout-required), it is preloaded on all routes
- if it's a [unique page](/docs/basic-features/pages), it is preloaded on the unique route for that page
- if it's in the [custom App](/docs/advanced-features/custom-app), it is preloaded on all the routes of the site under `/pages`

## Reusing fonts

Expand Down