font_face: Helpers for importing web fonts

In sass: Syntactically Awesome Style Sheets ('Sass')

Helpers for importing web fonts

Description

Include font file(s) when defining a Sass variable that represents a CSS font-family property.

Usage

font_google(
  family,
  local = TRUE,
  cache = sass_file_cache(sass_cache_context_dir()),
  wght = NULL,
  ital = NULL,
  display = c("swap", "auto", "block", "fallback", "optional")
)

font_link(family, href)

font_face(
  family,
  src,
  weight = NULL,
  style = NULL,
  display = c("swap", "auto", "block", "fallback", "optional"),
  stretch = NULL,
  variant = NULL,
  unicode_range = NULL
)

font_collection(..., default_flag = TRUE, quote = TRUE)

is_font_collection(x)

Arguments

family	A character string with a single font family name.
local	Whether or not download and bundle local (woff2) font files.
cache	A sass_file_cache() object (or, more generally, a file caching class with ⁠$get_file()⁠ and ⁠$set_file()⁠ methods). Set this argument to FALSE or NULL to disable caching.
wght	One of the following: NULL, the default weight for the family. A character string defining an axis range A numeric vector of desired font weight(s).
ital	One of the following: NULL, the default font-style for the family. 0, meaning font-style: normal 1, meaning font-style: italic c(0, 1), meaning both normal and italic
display	A character vector for the font-display ⁠@font-face⁠ property.
href	A URL resource pointing to the font data.
src	A character vector for the src ⁠@font-face⁠ property. Beware that is character strings are taken verbatim, so careful quoting and/or URL encoding may be required.
weight	A character (or numeric) vector for the font-weight ⁠@font-face⁠ property.
style	A character vector for the font-style ⁠@font-face⁠ property.
stretch	A character vector for the font-stretch ⁠@font-face⁠ property.
variant	A character vector for the font-variant ⁠@font-face⁠ property.
unicode_range	A character vector for unicode-range ⁠@font-face⁠ property.
...	a collection of font_google(), font_link(), font_face(), and/or character vector(s) (i.e., family names to include in the CSS font-family properly). Family names are automatically quoted as necessary.
default_flag	whether or not to include a !default when converted to a Sass variable with as_sass().
quote	whether or not to attempt automatic quoting of family names.
x	test whether x is a font_collection(), font_google(), font_link(), or font_face() object.

Details

These helpers must be used the named list approach to variable definitions, for example:

list(
  list("font-variable" = font_google("Pacifico")),
  list("body{font-family: $font-variable}")
)

Value

a sass_layer() holding an htmltools::htmlDependency() which points to the font files.

Font fallbacks

By default, font_google() downloads, caches, and serves the relevant font file(s) locally. By locally serving files, there's a guarantee that the font can render in any client browser, even when the client doesn't have internet access. However, when importing font files remotely (i.e., font_google(..., local = FALSE) or font_link()), it's a good idea to provide fallback font(s) in case the remote link isn't working (e.g., maybe the end user doesn't have an internet connection). To provide fallback fonts, use font_collection(), for example:

pacifico <- font_google("Pacifico", local = FALSE)
as_sass(list(
  list("font-variable" = font_collection(pacifico, "system-ui")),
  list("body{font-family: $font-variable}")
))

Default flags

These font helpers encourage best practice of adding a !default to Sass variable definitions, but the flag may be removed via font_collection() if desired.

as_sass(list("font-variable" = pacifico))
#> $font-variable: Pacifico !default;
as_sass(list("font-variable" = font_collection(pacifico, default_flag = F)))
#> $font-variable: Pacifico;

Serving non-Google fonts locally

Non-Google fonts may also be served locally with font_face(), but it requires downloading font file(s) and pointing src to the right location on disk. If you want src to be a relative file path (you almost certainly do), then you'll need to mount that resource path using something like shiny::addResourcePath() (for a shiny app) or servr::httd() (for static HTML).

References

https://developers.google.com/fonts/docs/css2

https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face

https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts

Examples

library(htmltools)

my_font <- list("my-font" = font_google("Pacifico"))
hello <- tags$body(
  "Hello",
  tags$style(
    sass(
      list(
        my_font,
        list("body {font-family: $my-font}")
      )
    )
  )
)

if (interactive()) {
  browsable(hello)
}

# Three different yet equivalent ways of importing a remotely-hosted Google Font
a <- font_google("Crimson Pro", wght = "200..900", local = FALSE)
b <- font_link(
  "Crimson Pro",
  href = "https://fonts.googleapis.com/css2?family=Crimson+Pro:wght@200..900"
)
url <- "https://fonts.gstatic.com/s/crimsonpro/v13/q5uDsoa5M_tv7IihmnkabARboYF6CsKj.woff2"
c <- font_face(
  family = "Crimson Pro",
  style = "normal",
  weight = "200 900",
  src = paste0("url(", url, ") format('woff2')")
)

sass documentation built on May 29, 2024, 11:51 a.m.