nuxt-font-loader

v2.3.5

Published

9 months ago

Simple, modern and lightweight font loader for Nuxt.

Downloads

16,899

0High
0Medium
0Low

ivodolenc

hypernym

nuxt nuxt-module nuxt-composables nuxt-font-composables nuxt-font-loader font-loader nuxt-font

Nuxt Font Loader

Simple, modern and lightweight font loader for Nuxt.

Repository | Package | Releases | Discussions

npm i -D nuxt-font-loader

Features

Helps you to easily load fonts on your site
Supports local and external loading
Provides font composables
Follows modern methods and practices
Designed for Nuxt 3+
TypeScript friendly
Super easy to use
No dependencies

Quick Start

Install nuxt-font-loader to your project

npm i -D nuxt-font-loader

Enable the module in the main config file

// nuxt.config.ts

{
  modules: ['nuxt-font-loader'],

  fontLoader: {
    local: [
      {
        src: '/new-font.woff2',
        family: 'Family Name',
        class: 'font-new-font'
      }
    ]
  }
}

That's it!

Optimization

The nuxt-font-loader brings an updated font loading strategies to your project. It automatically optimizes all your font sources and improves page loading speed.

Depending on the strategy, either local or external, the module adds preconnect and preload link tags to the <head> section with minified inline styles for @font-face rules.

So you don't have to worry about optimization at all since the module will do all the work under the hood.

Font Composables

The module also provides custom functions designed to load fonts on a specific page only.

Using this composables, the font sources will not be loaded globally, but only on the page from which the function is called.

This can be super useful if you want to change fonts for different pages or layouts.

By default, font composables are not automatically imported since they are optional, but you can enable this via module option.

// nuxt.config.ts

{
  fontLoader: {
    autoImport: true // enables auto-import feature
  }
}

If enabled, you can use font composables across your application without explicitly importing them.

Local Strategy

Loads fonts from the same domain as your deployment.

At the moment, this is the most recommended method for handling fonts. You can optimally load fonts with performance, flexibility and privacy in mind.

Also, try to use variable fonts whenever you can to take advantage of their customization and fast loading speed.

In addition, check out Nuxt Font, a much lighter version with the same API.

Global Settings

Place the previously downloaded fonts in the public/fonts/ directory and specify the path to the local font files.

// nuxt.config.ts

{
  fontLoader: {
    local: [
      {
        src: '/fonts/AspektaVF.woff2',
        family: 'Aspekta Variable',
        weight: '100 900',
        class: 'font-aspekta',
      },
    ]
  }
}

You can now use it in the templates like this:

<template>
  <h1 class="font-aspekta">Nuxt Font Loader</h1>
</template>

Font Composable

Import the function where you need it.

<!-- index.vue -->

<template>
  <h1 class="font-aspekta">Nuxt Font Loader</h1>
</template>

<script setup lang="ts">
  import { useLocalFont } from '#font-loader'

  useLocalFont([
    {
      src: '/fonts/AspektaVF.woff2',
      family: 'Aspekta Variable',
      weight: '100 900',
      class: 'font-aspekta',
    },
  ])
</script>

External Strategy

Loads fonts directly from third-party servers, such as Google, Typekit, etc.

Global Settings

Specify the full url to external font sources and adjust other options as needed.

// nuxt.config.ts

{
  fontLoader: {
    external: [
      {
        src: 'https://fonts.googleapis.com/css2?family=Inter&display=swap',
        family: 'Inter',
        class: 'font-inter',
      },
    ]
  }
}

You can now use it in the templates like this:

<template>
  <h1 class="font-inter">Nuxt Font Loader</h1>
</template>

Font Composable

Import the function where you need it.

<!-- index.vue -->

<template>
  <h1 class="font-inter">Nuxt Font Loader</h1>
</template>

<script setup lang="ts">
  import { useExternalFont } from '#font-loader'

  useExternalFont([
    {
      src: 'https://fonts.googleapis.com/css2?family=Inter&display=swap',
      family: 'Inter',
      class: 'font-inter',
    },
  ])
</script>

Options

Nuxt Font Loader has been completely rewritten so it's TypeScript friendly.

It also improves the development experience with detailed descriptions, examples, and auto-hinted configuration right in the code editor.

Defaults

// nuxt.config.ts

{
  fontLoader: {
    local: [],
    external: [],
    autoImport: false
  }
}

local

Type: object[]
Default: []

An array of objects that specifies local font sources.

Each object is treated as a separate block of rules.

// nuxt.config.ts

{
  fontLoader: {
    local: [
      {
        src: '/fonts/AspektaVF.woff2',
        family: 'Aspekta Variable',
        weight: '100 900',
        class: 'font-aspekta', // optional
      },
    ]
  }
}

preload

Type: boolean
Default: true

Specifies the preload links.

{
  preload: true
}

src

Type: string
Required: true

Specifies path to the font file.

{
  src: '/path/to/font.woff2'
}

family

Type: string
Required: true

Defines the font family name.

{
  family: 'Family Name'
}

fallback

Type: string
Default: undefined

Defines the font family fallback.

{
  fallback: 'sans-serif'
}

Example above will generate the font fallback:

.my-font {
  font-family: 'family-name', sans-serif;
}

weight

Type: string
Default: 400

Defines the font weight.

{
  // static weight
  weight: '300'
}

{
  // variable weight range
  weight: '100 900'
}

display

Type: string
Default: optional
Auto-hinted

Specifies how a font face is displayed.

{
  display: 'swap'
}

style

Type: string
Default: normal
Auto-hinted

Defines the font style.

{
  style: 'normal'
}

class

Type: string
Default: undefined

Defines the global css class for the current source.

{
  class: 'my-font'
}

Example above will generate global css class:

.my-font {
  font-family: 'family-name';
}

So it can be used in templates:

<h1 class="my-font">Font Loader</h1>

variable

Type: string
Default: undefined

Defines the global css variable for the current source.

{
  variable: 'my-font'
}

Example above will generate global css variable:

:root {
  --my-font: 'family-name';
}

So it can be used in templates:

h1 {
  font-family: var(--my-font);
}

unicode

Type: string[]
Default: undefined

Defines a specific range of characters to be used from the font.

{
  preload: false, // disables the preload link
  display: 'swap', // or 'fallback', 'auto' ...
  unicode: ['U+26']
}

Example above will generate:

@font-face {
  font-display: swap;
  unicode-range: U+26;
}

external

Type: object[]
Default: []

An array of objects that specifies external font sources.

It is also possible to specify static sources from the public/ directory.

Each object is treated as a separate block of rules.

// nuxt.config.ts

{
  fontLoader: {
    external: [
      {
        src: 'https://fonts.googleapis.com/css2?family=Inter&display=swap',
        family: 'Inter',
        class: 'font-inter', // optional
      },
    ]
  }
}

src

Type: string
Required: true

Specifies path to the external source.

{
  src: 'path-to-external-source'
}

family

Type: string
Default: undefined

Defines the font family name.

Use this in combination with the class or variable options.

{
  family: 'Family Name',
  class: 'my-font'
}

fallback

Type: string
Default: undefined

Defines the font family fallback.

{
  fallback: 'sans-serif'
}

Example above will generate the font fallback:

.my-font {
  font-family: 'family-name', sans-serif;
}

class

Type: string
Default: undefined

Defines the global css class for the current source.

{
  class: 'my-font'
}

Example above will generate global css class:

.my-font {
  font-family: 'family-name';
}

So it can be used in templates:

<h1 class="my-font">Font Loader</h1>

variable

Type: string
Default: undefined

Defines the global css variable for the current source.

{
  variable: 'my-font'
}

Example above will generate global css variable:

:root {
  --my-font: 'family-name';
}

So it can be used in templates:

h1 {
  font-family: var(--my-font);
}

autoImport

Type: boolean
Default: false

Manages the built-in auto-import feature.

If enabled, you can use font composables across your application without explicitly importing them.

// nuxt.config.ts

{
  fontLoader: {
    autoImport: true
  }
}

Community

Feel free to use the official discussions for any additional questions.

License

Developed in 🇭🇷 Croatia

Released under the MIT license.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Nuxt Font Loader

Features

Quick Start

Optimization

Font Composables

Local Strategy

Global Settings

Font Composable

External Strategy

Global Settings

Font Composable

Options

Defaults

local

preload

src

family

fallback

weight

display

style

class

variable

unicode

external

src

family

fallback

class

variable

autoImport

Community

License