google-fonts-css2

📜GOOGLE FONTS CSS 2

A Javascript package to integrate with Google Fonts API.

⚠️If you were using the v1 of this package check the new API below, it is slightly different.⚠️

• Single purpose: To provide an easy interface to create the latest version of a Google Fonts CSS2 URL.
• No dependencies.
• It adheres to the rules described on the current Google Fonts Documentation (CSS2).
• Works on browser and server side (SSR).
• Can create Material Symbols and Material Icons URLs

Read on for more information. Feel free to open issues or PRs.

How it works?

You say: Gimme Open Sans, from light to bold, italic. condensed and normal!

It answers: https://fonts.googleapis.com/css2?family=Open+Sans:ital,wdth,wght@1,75,300..700&family=Open+Sans:ital,wdth,wght@1,100,300..700&display=auto

• Getting Started
  • NodeJS, Browser, Common-JS, ES-Modules
  • Functions
  • Android, IOS & Flutter
• Google Fonts
  • Regular Fonts
  • Variable Fonts
  • Variable Fonts Options
• Google Material Symbols
  • Variable Symbols Options
• Google Material Icons
• Validations
• Examples

Getting Started

NodeJS, Browser, Common-JS, ES-Modules

This package is bundled to be used in multiple environments (ESM, CJS, UMD). Check the /dist folder for enviroment options.

Install

npm i google-fonts-css2

yarn add google-fonts-css2

<!-- directly in browser, note the /dist/umd path -->
<script src="https://cdn.jsdelivr.net/npm/google-fonts-css2@2.0.0/dist/umd/index.min.js"></script>

Import

You can seamlessly import or require:

import { getGoogleFontsUrl, getGoogleFontsUrlSimple } from "google-fonts-css2"

or

const { getGoogleFontsUrl, getGoogleFontsUrlSimple } = require("google-fonts-css2")

or

For HTML check the codepen: https://codepen.io/adrianotirloni/pen/ExEWbdd

Functions

📜 getGoogleFontsUrlSimple

This function calls getGoogleFontsUrl but with simpler argurments and reduced options.

• Arguments: Any number of strings or objects.

• Strings: Directive family style strings - All spaces and cases are removed from the string, except for the Font Family name.

• Objects: Directive family style objects or a options object.

Strings format: "<case-sensitive-spaced font name>,<weights>,<?italic> or <?widths>" Objects

• Options object: {display: , onlyThisCharacters: }
• Font Style object: Same as getGoogleFontsUrl function (this allow full directive request).

Examples (open urls in browser to check it):

//Open Sans - Named regular weight
getGoogleFontsUrlSimple('Open Sans, regular')
//=> https://fonts.googleapis.com/css2?family=Open+Sans:wght@400&display=auto

//Open Sans - Named regular weight, with options object
getGoogleFontsUrlSimple(
  {display: "swap", onlyThisCharacters: "abcd"}, 
  "Open Sans, regular"
)
//=> https://fonts.googleapis.com/css2?family=Open+Sans:wght@400&display=swap&text=abcd

//Multiple arguments, multiple fonts, unordered
getGoogleFontsUrlSimple("Open Sans, 300, italic", {display: "swap"}, "Lato, regular")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@1,300&family=Lato:wght@400&display=swap	
	
//Open Sans - Numbered regular weight
getGoogleFontsUrlSimple("Open Sans, 400")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:wght@400&display=auto

//Open Sans - Multiple Named and Numbered weight
getGoogleFontsUrlSimple("Open Sans, regular & 600")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:wght@400&family=Open+Sans:wght@600&display=auto

//Open Sans - Multiple Named weight
getGoogleFontsUrlSimple("Open Sans, regular & semibold & bold")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:wght@400&family=Open+Sans:wght@600&family=Open+Sans:wght@700&display=auto

//Open Sans - Ranged weight
getGoogleFontsUrlSimple("Open Sans, 300..800")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:wght@300..800&display=auto

//Open Sans - Regular Italic
getGoogleFontsUrlSimple("Open Sans, 400, italic")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@1,400&display=auto

//Open Sans - Full weight range, italic and named width
getGoogleFontsUrlSimple("Open Sans, 300..800, italic, condensed & normal")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:ital,wdth,wght@1,75,300..800&family=Open+Sans:ital,wdth,wght@1,100,300..800&display=auto

//Open Sans - Full weight range, WITHOUT italic and named width
getGoogleFontsUrlSimple("Open Sans, 300..800, condensed & semiCondensed & normal")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:wdth,wght@75,300..800&family=Open+Sans:wdth,wght@87.5,300..800&family=Open+Sans:wdth,wght@100,300..800&display=auto

//Open Sans - Full weight range, with italic and full ranged width
getGoogleFontsUrlSimple("Open Sans, 300..800, 75..100, italic")
//=> https://fonts.googleapis.com/css2?family=Open+Sans:ital,wdth,wght@1,75..100,300..800&display=auto

📜 getGoogleFontsUrl

The full base function to construct the urls. Check a live example here: https://codepen.io/adrianotirloni/pen/wvmJxpG

• Arguments: An array of objects (Font Families), Display, OnlyThisCharacters
• Display: 'auto' | 'block' | 'swap' | 'fallback' | 'optional'
• OnlyThisCharacters: Optional, string.
• Font Family Object:
  • family: Case sensitive font family name, as per Google Fonts website.
  • styles: Array of Font Styles Objects available to the chosen family.
  • Font Style Object:

    • Any number of directive pairs: <axisDirective>: <axisOption>

    • Axis Directive: wght (axis symbol) or weight (humanized name)

      • Examples: ital or italic, XOPQ or thickStroke

    • Axis Option: Number, String or Range

      • Range: [Number, Number] or [String, Number] or [String, String] or "StrNumber..StrNumber"
      • Number: Negative or positive with decimal places accordingly to selected Font
      • String: Number or Range representation as String.

	
getGoogleFontsUrl([
  {
    family: 'Roboto Flex', 
    styles: [ 
      {weight: '800..1000', width: [25, 150], slant: -5, figureHeight: 500},
      {weight: 300},
      {weight: 400},
    ]
  },
  {
    family: 'Open Sans', 
    styles: [ 
      {weight: '400', italic: 1},
    ]
  }
], 'swap', 'abcdefgh')
	
getGoogleFontsUrl(
  [
    {
      family: 'Material Icons',
      styles: [
        { wght: '500', wght: '501' }
      ]
    }
  ],
  'swap'
)
      
getGoogleFontsUrl([
  {
    family: 'Roboto Flex',
    styles: [
      { weight: '100..500', width: [-10, 0] }
    ]
  }
], 'swap')

Android, IOS & Flutter

Android, IOS and Flutter implementation are not the same as web implementation https://developers.google.com/fonts/docs/android, so is out of the scope of this package.

(If you know a library for tose tools open a PR to this document listing it here)

Google Fonts

Regular Fonts

Google Fonts has as of today 1429 font families, of those, 1176 are regular fonts. Regular Fonts are those that don't have a variable directive axis, like weight.

As an example, a regular font will have 400,500,600 weight. A Font with a variable weight axis will have every integer from 400 to 600. (401, 476 ... 599, 600)

Variable Fonts

A Variable Font can have one or multiple directive axis as a varaible axis. A variable font can have standard weights (400,500,600) but a variable width axis (from 1 to 150). This font will be considered variable.

You can check all variable fonts and their directive axes on this link: https://fonts.google.com/variablefonts

Variable Fonts Options

Variable or Regular fonts may have any number of directive axes.

Google API will only accept the axis symbol on a specific order, to make readability better this package will allow the use of the case-sensitive symbol AND/OR human readable name

The avaliable directives symbol and human names are below:

italic: ital
opticalSize: opsz
slant: slnt
weight: wght
width: wdth
ascenderHeight: YTAS
casual: CASL
counterWidth: XTRA
cursive: CRSV
descenderDepth: YTDE
figureHeight: YTFI
fill: FILL
grade: GRAD
lowercaseHeight: YTLC
monospace: MONO
softness: SOFT
thickStroke: XOPQ
thinStroke: YOPQ
uppercaseHeight: YTUC	

You can read about each on: https://fonts.google.com/variablefonts#axis-definitions

Input Validation

• ✅ Validates the existence of the directive axis used. (weight or wght, opticalSize or opsz)
• ✅ Ignores duplicate directives (wght) and uses the latest one.
• ❌ Does not validate if the font requested has the directive in its options. Eg: If you request Open Sans, asking for slant -10 the URL will properly be created BUT Google will return a 400 answer as the slant directive is not avaliable for Open Sans

Examples

• HTML Import: https://codepen.io/adrianotirloni/pen/ExEWbdd
• Function use: https://codepen.io/adrianotirloni/pen/wvmJxpG