A Javascript package to integrate with Google Fonts API.
npm install google-fonts-css2⚠️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!
------------
- 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
---
This package is bundled to be used in multiple environments (ESM, CJS, UMD).
Check the /dist folder for enviroment options.
``console`
npm i google-fonts-css2console`
yarn add google-fonts-css2html`
or require:`javascript
import { getGoogleFontsUrl, getGoogleFontsUrlSimple } from "google-fonts-css2"
`
or
javascript
const { getGoogleFontsUrl, getGoogleFontsUrlSimple } = require("google-fonts-css2")
`
or https://codepen.io/adrianotirloni/pen/ExEWbdd$3
#### 📜 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: "
,, or "
Objects
1) Options object: {display: , onlyThisCharacters: }
2) Font Style object: Same as getGoogleFontsUrl function (this allow full directive request).
##### Examples (open urls in browser to check it):
`javascript
//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:
- 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:
- Axis Directive: (axis symbol) or weight (humanized name)
- Examples: ital or italic, XOPQ or thickStroke
- Axis Option: Number, String or Range
- Range: 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 picturejavascript
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')
`
$3
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
$3
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 .
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)
$3
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
$3
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:
yaml
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. (, 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