Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ivodolenc/nuxt-font-loader

Handles your fonts with ease.
https://github.com/ivodolenc/nuxt-font-loader

font-loader module nuxt nuxt-font nuxt-font-loader nuxt-module webfont

Last synced: about 1 month ago
JSON representation

Handles your fonts with ease.

Awesome Lists containing this project

README 

        
# Nuxt Font Loader



Simple, modern and lightweight font loader for Nuxt.



Repository | Package | Releases | Discussions



```sh

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



1. Install `nuxt-font-loader` to your project



```sh

npm i -D nuxt-font-loader

```



2. Enable the module in the main config file



```js

// 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 `` 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.



```js

// 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](https://github.com/hypernym-studio/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.



```js

// 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:



```html



  
Nuxt Font Loader



```



### Font Composable



Import the function where you need it.



```html



  
Nuxt Font Loader



  import { useLocalFont } from '#font-loader'



  useLocalFont([

    {

      src: '/fonts/AspektaVF.woff2',

      family: 'Aspekta Variable',

      weight: '100 900',

      class: 'font-aspekta',

    },

  ])



```



## 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.



```js

// 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:



```html



  
Nuxt Font Loader



```



### Font Composable



Import the function where you need it.



```html



  
Nuxt Font Loader



  import { useExternalFont } from '#font-loader'



  useExternalFont([

    {

      src: 'https://fonts.googleapis.com/css2?family=Inter&display=swap',

      family: 'Inter',

      class: 'font-inter',

    },

  ])



```



## 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



```js

// 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.



```js

// 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.



```js

{

  preload: true

}

```



### src



- Type: `string`

- Required: `true`



Specifies path to the font file.



```js

{

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

}

```



### family



- Type: `string`

- Required: `true`



Defines the font family name.



```js

{

  family: 'Family Name'

}

```



### fallback



- Type: `string`

- Default: `undefined`



Defines the font family fallback.



```js

{

  fallback: 'sans-serif'

}

```



Example above will generate the font fallback:



```css

.my-font {

  font-family: 'family-name', sans-serif;

}

```



### weight



- Type: `string`

- Default: `400`



Defines the font weight.



```js

{

  // static weight

  weight: '300'

}

```



```js

{

  // variable weight range

  weight: '100 900'

}

```



### display



- Type: `string`

- Default: `optional`

- Auto-hinted



Specifies how a font face is displayed.



```js

{

  display: 'swap'

}

```



### style



- Type: `string`

- Default: `normal`

- Auto-hinted



Defines the font style.



```js

{

  style: 'normal'

}

```



### class



- Type: `string`

- Default: `undefined`



Defines the global css _class_ for the current source.



```js

{

  class: 'my-font'

}

```



Example above will generate global css class:



```css

.my-font {

  font-family: 'family-name';

}

```



So it can be used in templates:



```html

Font Loader


```



### variable



- Type: `string`

- Default: `undefined`



Defines the global css _variable_ for the current source.



```js

{

  variable: 'my-font'

}

```



Example above will generate global css variable:



```css

:root {

  --my-font: 'family-name';

}

```



So it can be used in templates:



```css

h1 {

  font-family: var(--my-font);

}

```



### unicode



- Type: `string[]`

- Default: `undefined`



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



```js

{

  preload: false, // disables the preload link

  display: 'swap', // or 'fallback', 'auto' ...

  unicode: ['U+26']

}

```



Example above will generate:



```css

@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.



```js

// 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.



```js

{

  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.



```js

{

  family: 'Family Name',

  class: 'my-font'

}

```



### fallback



- Type: `string`

- Default: `undefined`



Defines the font family fallback.



```js

{

  fallback: 'sans-serif'

}

```



Example above will generate the font fallback:



```css

.my-font {

  font-family: 'family-name', sans-serif;

}

```



### class



- Type: `string`

- Default: `undefined`



Defines the global css _class_ for the current source.



```js

{

  class: 'my-font'

}

```



Example above will generate global css class:



```css

.my-font {

  font-family: 'family-name';

}

```



So it can be used in templates:



```html

Font Loader


```



### variable



- Type: `string`

- Default: `undefined`



Defines the global css _variable_ for the current source.



```js

{

  variable: 'my-font'

}

```



Example above will generate global css variable:



```css

:root {

  --my-font: 'family-name';

}

```



So it can be used in templates:



```css

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.



```js

// nuxt.config.ts



{

  fontLoader: {

    autoImport: true

  }

}

```



## Community



Feel free to use the official [discussions](https://github.com/ivodolenc/nuxt-font-loader/discussions) for any additional questions.



## License



Developed in 🇭🇷 Croatia



Released under the [MIT](LICENSE.txt) license.



© Ivo Dolenc