google-fonts-css2
v2.0.2
Published
A Javascript package to integrate with Google Fonts API.
Downloads
819
Maintainers
Readme
📜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!
- Getting Started
- Google Fonts
- 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/[email protected]/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:[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=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) orweight
(humanized name)- Examples:
ital
oritalic
,XOPQ
orthickStroke
- 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 & 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 a400
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