external_link: External link
In shinyGovstyle: Custom Gov Style Inputs for Shiny

View source: R/external_link.R

external_link

R Documentation

External link

Description

It is commonplace for external links to open in a new tab, and when we do this we should be careful...

This function automatically adds the following to your link:

target="_blank" to open in new tab
rel="noopener noreferrer" to prevent reverse tabnabbing

By default this function also adds "(opens in new tab)" to your link text to warn users of the behaviour.

This also adds "This link opens in a new tab" as a visually hidden span element within the HTML outputted to warn non-visual users of the behaviour.

The function will error if you end with a full stop, give a warning for particularly short link text and will automatically trim any leading or trailing white space inputted into link_text.

If you are displaying lots of links together and want to save space by avoiding repeating (opens in new tab), then you can set add_warning = FALSE and add a line of text above all of the links saying something like 'The following links open in a new tab'.

Setting add_warning = FALSE removes the visible text warning entirely, so sighted users lose the visual cue that the link behaves differently. Set add_warning = "icon" instead to add a small decorative arrow icon after the link text, giving sighted users a visual warning without repeating the full "(opens in new tab)" text. The icon is purely decorative (hidden from screen readers, which still get the same hidden warning as add_warning = FALSE), so it should be paired with an explanatory sentence above a group of links, not relied on as the only warning.

If href starts with ⁠mailto:⁠ (case-insensitive), the new-tab behaviour is skipped entirely: no target="_blank"/rel="noopener noreferrer", no "(opens in new tab)" text or hidden span, and add_warning = "icon" has no effect, since a mailto link hands off to the mail client rather than opening a new browser tab. link_text validation still applies as normal.

Usage

external_link(href, link_text, add_warning = TRUE, footer = FALSE)

Arguments

`href`	URL that you want the link to point to
`link_text`	Text that will appear describing your link, must be descriptive of the page you are linking to. Vague text like 'click here' or 'here' will cause an error, as will ending in a full stop. Leading and trailing white space will be automatically trimmed. If the string is shorter than 7 characters a console warning will be thrown. There is no way to hush this other than providing more detail
`add_warning`	One of TRUE (default), FALSE, or "icon", controlling how users are warned that the link opens in a new tab. TRUE appends "(opens in new tab)" to the visible link text. FALSE removes the visible text (a visually hidden span still warns screen reader users) with no replacement visual cue, for use with an explanatory sentence above a group of links. "icon" behaves like FALSE but also adds a small decorative arrow icon after the link text, giving sighted users a visual cue without repeating the full text. Be careful and consider accessibility before moving away from the default. Has no effect when `href` is a `⁠mailto:⁠` link.
`footer`	Apply standard GDS footer CSS styling. Logical, default = FALSE

Details

Intentionally basic wrapper for HTML anchor elements making it easier to create safe external links with standard and accessible behaviour. For more information on how the tag is generated, see htmltools::tags().

Value

shiny tag object

Examples

external_link("https://shiny.posit.co/", "R Shiny")

external_link(
  "https://shiny.posit.co/",
  "R Shiny",
  add_warning = FALSE
)

# Give sighted users a visual warning without repeating the text
external_link(
  "https://shiny.posit.co/",
  "R Shiny",
  add_warning = "icon"
)

# This will trim and show as 'R Shiny'
external_link("https://shiny.posit.co/", "  R Shiny")

# mailto: links skip the new-tab attributes, text, and icon
external_link("mailto:feedback@example.com", "feedback@example.com")

# Example of within text
shiny::tags$p(
  "Oi, ", external_link("https://shiny.posit.co/", "R Shiny"), " is great."
)

# Example of multiple links together
shiny::tags$h2("Related resources")
shiny::tags$p("The following links open in a new tab.")
gov_list(
  list = list(
    external_link(
      "https://shiny.posit.co/",
      "R Shiny documentation",
      add_warning = FALSE
    ),
    external_link(
      "https://www.python.org/",
      "Python documentation",
      add_warning = FALSE
    ),
    external_link(
      "https://nextjs.org/",
      "Next.js documentation",
      add_warning = FALSE
    )
  ),
  style = "bullet"
)

shinyGovstyle documentation built on Oct. 16, 2026, 1:07 a.m.