R: Helpers for importing web fonts

font_google {sass} | R Documentation

## 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 (woff) 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')")
    )

[Package sass version 0.4.0 Index]