⚠️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.
You say: Gimme Open Sans, from light to bold, italic. condensed and normal!
- Getting Started
- Google Fonts
- 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.
npm i google-fonts-css2yarn add google-fonts-css2<!-- directly in browser, note the /dist/umd path -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/index.min.js"></script>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
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).
//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:[email protected]&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,[email protected],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=autoThe 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) orweight(humanized name)- Examples:
italoritalic,XOPQorthickStroke
- Examples:
-
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.
- Range:
-
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 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 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)
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 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
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
- ✅ 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 -10the URL will properly be created BUT Google will return a400answer as the slant directive is not avaliable for Open Sans
- HTML Import: https://codepen.io/adrianotirloni/pen/ExEWbdd
- Function use: https://codepen.io/adrianotirloni/pen/wvmJxpG
- Open Sans and Cursive multiple usage example: https://codepen.io/adrianotirloni/pen/gOemBxd