font_google {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')")
)