README.Rmd

---
title: xaringanExtra
output: github_document
always_allow_html: true
---

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/xaringanExtra)](https://CRAN.R-project.org/package=xaringanExtra)
[![xaringanExtra status badge](https://gadenbuie.r-universe.dev/badges/xaringanExtra)](https://gadenbuie.r-universe.dev)
[![R-CMD-check](https://github.com/gadenbuie/xaringanExtra/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/gadenbuie/xaringanExtra/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

```{r include=FALSE}
INCLUDE_CHILD_HEADER <- FALSE
IN_README <- TRUE
```

<!-- Links -->
[xaringan]: https://slides.yihui.org/xaringan
[remarkjs]: https://remarkjs.com/
[animate.css]: https://daneden.github.io/animate.css/
[text-poster]: https://github.com/IMAGINARY/text-poster#readme

`xaringanExtra` is a playground of enhancements and extensions for [xaringan] slides.

- Add an overview of your presentation with [tile view](#-tile-view)
- Make your slides [editable](#-editable)
- Share your slides in style with [share again](#-share-again)
- Broadcast your slides in real time to viewers with [broadcast](#-broadcast)
- Scribble on your slides during your presentation with [scribble](#-scribble)
- Announce slide changes with a [subtle tone](#-slide-tone)
- Animate slide transitions with [animate.css](#-animatecss)
- Add tabbed panels to slides with [panelset](#-panelset)
- Add a logo to all of your slides with [logo](#-logo)
- Add a top or bottom banner to all of your slides with [banner](#-banner)
- Add a search box to search through your slides with [search](#-search)
- Use the [Tachyons CSS utility toolkit](#-tachyons)
- Add a live video feed of your [webcam](#-webcam)
- Add one-click code copying with [clipboard](#-clipboard)
- Always play gifs from the start with [freezeframe](#-freezeframe)
- Fit your slides to [fill the browser window](#-fit-to-screen)
- Add [extra CSS styles](#-extra-styles)

Each item can be enabled separately,
or load everything at once with a single call.

````markdown
```{r xaringanExtra, echo=FALSE}`r ''`
xaringanExtra::use_xaringan_extra(c("tile_view", "animate_css", "tachyons"))
```
````

## Installation

You can install the released version of xaringanExtra from CRAN:

``` r
install.packages("xaringanExtra")
```

You can install the latest development version from [GitHub](https://github.com/gadenbuie/xaringanExtra/):

``` r
# install.packages("remotes")
remotes::install_github("gadenbuie/xaringanExtra")
```

or from [gadenbuie.r-universe.dev](https://gadenbuie.r-universe.dev/):

``` r
options(repos = c(
  gadenbuie = 'https://gadenbuie.r-universe.dev',
  CRAN = 'https://cloud.r-project.org'
))

install.packages('xaringanExtra')
```


## &#x1F5FA; Tile View

#### &#x1F4FA; [Tile View Demo](https://pkg.garrickadenbuie.com/xaringanExtra/tile-view/)

Tile view gives you a way to quickly jump between slides.
Just press <kbd>O</kbd>
(the letter **O** for **O**verview)
at any point in your slideshow and the tile view appears.
Click on a slide to jump to the slide, or press <kbd>O</kbd> to exit tile view.

![](man/figures/tile-view.png)

To add tile view to your xaringan presentation,
add the following code chunk to your slides' R Markdown file.

````markdown
```{r xaringan-tile-view, echo=FALSE}`r ''`
xaringanExtra::use_tile_view()
```
````

Tile view is heavily inspired by
(and is essentially a port to Vanilla JavaScript of)
[a jQuery remarkjs hook](https://github.com/StephenHesperus/remark-hook/)
by the same name by [Stephen Hesperus](https://github.com/StephenHesperus).

## &#x1F4DD; Editable

#### &#x1F4FA; [Editable Demo](https://pkg.garrickadenbuie.com/xaringanExtra/editable/)

Editable gives you a way to write directly inside your slides,
updating your content live.
Make any element of your slides editable by using the `.can-edit[...]` class.

![](man/figures/editable.gif)

Make your slides editable with the following code chunk.

````markdown
```{r xaringan-editable, echo=FALSE}`r ''`
xaringanExtra::use_editable(expires = 1)
```
````

Then, to make a component of your slides editable,
use the `.can-edit[]` class.

```markdown
## .can-edit[You can edit this slide title]
```

Editable fields that only have the `.can-edit` class
are reset whenever the slides are re-loaded in your browser.
If you want to store the edited values and
have them persist across browser sessions,
give each editable field a `.key-<NAME>` class.
Be sure to make each key unique and
note that the key name must be a valid CSS class,
i.e. it cannot contain spaces.

```markdown
## .can-edit.key-firstSlideTitle[Change this title and then reload the page]
```

For more complicated HTML elements,
it's best to make only spans of text editable, such as

```
Hello, .can-edit[world], and welcome to my talk!
```

or to use placeholder text.

```markdown
## A few of my favorite things

.can-edit.key-likes[
- thing one
- thing two
]
```

## &#x1F4FC; Share Again

#### &#x1F4FA; [Share Again](https://pkg.garrickadenbuie.com/xaringanExtra/share-again/share-again.html)

Share your slides in style with _share again_!
It adds a share bar to your slides that only shows up when they're embedded in another page.
The bar adds easy slide navigation, quick access to full screen views,
and a share menu for one-click (or tap!) sharing on social media sites.

![](man/figures/meet-share-again.jpg)

Add share again to your slides in three easy steps.

1. Add `use_share_again()` to your slides

    ````markdown
    ```{r share-again, echo=FALSE}`r ''`
    xaringanExtra::use_share_again()
    ```
    ````

1. Style your share bar and choose social media sites

    ````markdown
    ```{r style-share-again, echo=FALSE}`r ''`
    xaringanExtra::style_share_again(
      share_buttons = c("twitter", "linkedin", "pocket")
    )
    ```
    ````

1. Embed your slides in [blogdown](https://bookdown.org/yihui/blogdown/) or R Markdown websites

    ````markdown
    ```{r embed-xaringan, echo=FALSE}`r ''`
    xaringanExtra::embed_xaringan(url = "share-again.html", ratio = "4:3")
    ```
    ````

    `embed_xaringan()` works with
    <span style="text-decoration: underline">any</span> xaringan presentation,
    _share again_ not required!

    Here's what your [slides will look like](https://pkg.garrickadenbuie.com/xaringanExtra/share-again/)
    in an R Markdown HTML document.

## &#x1F4E1; Broadcast

#### &#x1F4FA; [Broadcast Demo](https://pkg.garrickadenbuie.com/xaringanExtra/broadcast/)

**Broadcast** lets others follow along, in real time!
Built with [PeerJS](https://peerjs.com),
**broadcast** give you a unique URL to share with your viewers.
Then, when they load your slides,
their slides will automatically follow you as you present!

```{r child="man/fragments/broadcast-details.Rmd"}
```

## &#x1F469;&#x200D;&#x1F3A8; Scribble

#### &#x1F4FA; [Scribble Demo](https://pkg.garrickadenbuie.com/xaringanExtra/scribble/)

Scribble lets you draw on your [xaringan](https://slides.yihui.org/xaringan) slides.
Click the *pencil* icon or press <kbd>S</kbd> to begin drawing.
Pressing <kbd>S</kbd> or starting the drawing mode toggles the scribble toolbox.
There, you'll find the *eraser* button, which helps you remove lines from your drawing.
Or click the *trash* button to clear the drawings on the current slide.

````markdown
```{r xaringan-scribble, echo=FALSE}`r ''`
xaringanExtra::use_scribble()
```
````

Your drawings stay with each slide when you change slides.
Note that you won't be able to change slides while you're in drawing mode.
In fact, you can use the <kbd>&larr;</kbd> and <kbd>&rarr;</kbd> keys
to **undo** or **redo** your drawings.

Remember that if you use slide continuations to partially reveal slide contents,
each partial slide is technically a _brand-new_ slide as far as xaringan is concerned.
This means that each partial slide will have it's own drawing layer
and your drawings on one slide won't carry over to the next.
(But they'll still be there when you switch back!)

To save a copy of the slide with your drawings,
your best option is to print your presentation from the browser.

## &#x1F50A; Slide Tone

#### &#x1F4FA; [Slide Tone Demo](https://pkg.garrickadenbuie.com/xaringanExtra/slide-tone/)

Slide tone plays a subtle sound when you change slides.
It was
[requested by a blind R user](https://github.com/yihui/xaringan/issues/214)
and enables users to hear an auditory signal of their progress through the slides.

The tones increase in pitch for each slide from a low C to a high C note.
The tone pitch stays the same for incremental slides.

Visit the
[slide tone demo slides](https://pkg.garrickadenbuie.com/xaringanExtra/slide-tone/)
to experience it yourself.
Or include slide tone in your next xaringan presentation
by adding the following code chunk to your slides' R Markdown.

````markdown
```{r xaringan-slide-tone, echo=FALSE}`r ''`
xaringanExtra::use_slide_tone()
```
````

## &#x1F4FD; Animate.css

#### &#x1F4FA; [Animate.css Demo](https://pkg.garrickadenbuie.com/xaringanExtra/animate-css/)

[Animate.css] is a popular collection of CSS animations. It contains

> a bunch of cool, fun, and cross-browser animations for you to use in your
> projects. Great for emphasis, home pages, sliders, and general
> just-add-water-awesomeness.

Use `use_animate_css()` to include the animate.css stylesheets in your slides.
This function automatically modifies the CSS selector that enables the animation
so that only the slides that are visible are animated.
This drastically improves performance on large slide decks with many animations.
For use in other HTML documents,
set `xaringan = FALSE` to load the default `animate.css` file
without this performance tweak.

To use animate.css in your slides,
add the following code chunk to your slides' R Markdown.

````markdown
```{r xaringan-animate-css, echo=FALSE}`r ''`
xaringanExtra::use_animate_css()
```
````

Then add the `animated` class and the [desired animation class][animate.css] to the slides you want to animate.
`Out` animations are only applied to slides on exit.

```markdown
---
class: animated slideInRight fadeOutLeft

## This slide...

- slides in from the right
- and fades out to the left on exit
```

If you want to use the same slide transitions for all slides,
you can use `use_animate_all()`.
This function sets a default in and out animation for all slides.
Animations can be disabled for individual slides
by adding the class `no-animation` to the slide.

````markdown
```{r xaringan-animate-all, echo=FALSE}`r ''`
xaringanExtra::use_animate_all("slide_left")
```
````

Note: because `use_animate_all()` only imports the CSS required for the slide in and slide out animations,
you need to also include `use_animate_css()` (see above)
if you want to use other animations from `animate.css` in your slides.

## &#x1F5C2; Panelset

#### &#x1F4FA; [Panelset Demo](https://pkg.garrickadenbuie.com/xaringanExtra/panelset/)

Panelset adds accessible tabbed panels —
just like R Markdown's `.tabset` panels —
to your xaringan slides.
You can activate a panel by clicking on the tab,
or you can use the keyboard.
When you reach a slide with a panelset,
the left and right arrows will step through the panels.

To use panelset, add the following chunk to your slides.

````markdown
```{r xaringan-panelset, echo=FALSE}`r ''`
xaringanExtra::use_panelset()
```
````

![](man/figures/panelset.gif)

Then, create a `.panelset[...]` that contains `.panel[]`s.
Each `.panel[]` should have a `.panel-name[]` and content
(everything that isn't the panel's name).

```markdown
.panel[.panel-name[NAME]
...content...
]
```

Here's the example used in the demo slides.

````markdown
.panelset[
.panel[.panel-name[R Code]

```{r panel-chunk, fig.show='hide'}`r ''`
# ... r code ...
```
]

.panel[.panel-name[Plot]

![](`r knitr::fig_chunk("panel-chunk", ".png")`)
]
]
````

### Sideways Panelsets

```{r child="man/fragments/panelset_sideways.Rmd"}
```

### Use in R Markdown

[rmarkdown::html_document()]: https://rmarkdown.rstudio.com/docs/reference/html_document.html


[Example R Markdown output with panelset](https://pkg.garrickadenbuie.com/xaringanExtra/panelset//rmarkdown.html)

```{r child="man/fragments/panelset_other-rmd.Rmd"}
```

### Customize Panelset Appearance

```{r child="man/fragments/panelset_custom-styles.Rmd"}
```

### Panelset knitr Chunks

```{r child="man/fragments/panelset_chunks.Rmd"}
```

## &#x1F48C; Logo

#### &#x1F4FA; [Logo Demo](https://pkg.garrickadenbuie.com/xaringanExtra/logo/)

`use_logo()` adds a logo to all of your slides.
You can make the logo a clickable link and choose where on the slide it is placed.
You can also set which types of slides will not get the logo by default.

To add a logo to your xaringan presentation,
add the following code chunk to your slides' R Markdown file.

````markdown
```{r xaringan-logo, echo=FALSE}`r ''`
xaringanExtra::use_logo(
  image_url = "https://raw.githubusercontent.com/rstudio/hex-stickers/master/PNG/xaringan.png"
)
```
````

See the documentation for `?use_logo` for more options regarding sizing
and positioning. You can also make the logo a link using `link_url` and
you can hide the logo for a particular slide by using the `hide_logo`
slide class.

## &#x1F4F0; Banner

#### &#x1F4FA; [Banner Demo](https://pkg.garrickadenbuie.com/xaringanExtra/banner/)

`use_banner()` adds a banner to the top or the bottom of your slides.
Use banner to add the title of your talk,
a link to your materials online,
or any other text to every slide.
Each banner has three columns: left, center, and right.
Choose to `exclude` the banner from particular slides by class.

````markdown
```{r xaringan-banner, echo=FALSE}`r ''`
xaringanExtra::use_banner(
  top_left = "My Awesome Talk Title",
  top_right = "Mr. Fancy Pants",
  bottom_left = "bit.ly/my-awesome-talk",
  exclude = "title-slide"
)
```
````

Banners are fully customizable and can be styled based on slide class,
although the defaults will generally work in most places.
See `style_banner()` for full details!

## &#x1F50D; Search

#### &#x1F4FA; [Search Demo](https://pkg.garrickadenbuie.com/xaringanExtra/search/)

Brings [remark.search](https://github.com/arestivo/remark.search) to xaringan slides! Call `use_search()` to add **search** to your slides and to choose your options.

````markdown
```{r xaringanExtra-search, echo=FALSE}`r ''`
xaringanExtra::use_search(show_icon = TRUE)
```
````

| Parameter | Description |
|:-|:-|
| `position` | Where to place the search box. |
| `case_sensitive` | If <code>FALSE</code>, ignores case of search and text. |
| `show_icon` | Show the icon to open or close the search? |
| `auto_search` | Search on each keystroke (<code>TRUE</code>) or on enter (<code>FALSE</code>)? |

In your slides, press <kbd>Control</kbd> + <kbd>F</kbd> to start searching, or click on the search icon &#x1F50D; if you set `show_icon = TRUE`. Press <kbd>Enter</kbd> to jump to the next match.

To change the appearance of the **search** box, use `style_search()`:

````markdown
```{r xaringanExtra-search-style, echo=FALSE}`r ''`
xaringanExtra::style_search(match_background = "pink")
```
````

| Argument | Description |
|:-|:-|
| `icon_fill` | Color of search icon |
| `input_background` | Color of search input box background |
| `input_foreground` | Color of text in search input box |
| `input_border` | Border style of search input box |
| `match_background` | Color of match background (not current) |
| `match_foreground` | Color of match text (not current) |
| `match_current_background` | Color of current match background |
| `match_current_foreground` | Color of current match text |
| `selector` | CSS selector specifying which search bar to update (for advanced or unusual uses only) |


## &#x1F3D7; Tachyons

#### &#x1F4FA; [Tachyons Demo](https://pkg.garrickadenbuie.com/xaringanExtra/tachyons/)

[tachyons]: http://tachyons.io/
[tachyons-docs]: http://tachyons.io/docs/
[tachyons-cheatsheet]: https://roperzh.github.io/tachyons-cheatsheet/

[Tachyons] is a collection of CSS utility classes
that works beautifully with [xaringan] presentations
and the [remarkjs] class syntax.

To use tachyons in your slides,
add the following code chunk to your slides' R Markdown.

````markdown
```{r xaringan-tachyons, echo=FALSE}`r ''`
xaringanExtra::use_tachyons()
```
````

Tachyons provides small, single-purpose CSS classes that are easily composed to achieve larger functionality and styles.
In the
[remarkjs content classes syntax](https://github.com/gnab/remark/wiki/Markdown#content-classes),
you can compose classes by chaining them together.
For example,
the following markdown produces a box with a
washed green background (`.bg-washed-green`)
and a dark green border (`.b--dark-green`)
on all sides (`.ba`)
with line width 2 (`.bw2`)
and border radius (`.br3`).
The box has a shadow (`.shadow-5`)
and medium-large horizontal padding (`.ph4`)
with a large top margin (`.mt5`).

```markdown
.bg-washed-green.b--dark-green.ba.bw2.br3.shadow-5.ph4.mt5[
The only way to write good code is to write tons of bad code first.
Feeling shame about bad code stops you from getting to good code

.tr[
— Hadley Wickham
]]
```

![](man/figures/tachyons.png)

Tachyons provides hundreds of CSS classes that are abbreviated and terse,
so it takes some time to learn.
In addition to the [tachyons documentation][tachyons-docs],
the [Tachyons Cheatsheet][tachyons-cheatsheet] is an excellent and easy to use reference.

## &#x1F933; Webcam

#### &#x1F4FA; [Webcam Demo](https://pkg.garrickadenbuie.com/xaringanExtra/webcam/)

Add a live video of your webcam into your slides (in your own browser only).
Useful when you are presenting via video conference to include your video,
or when you are recording a class or lecture.

```{r child="man/fragments/webcam-details.Rmd"}
```

The webcam extension is based on the original
[webcam implementation](https://yihui.org/en/2017/12/html5-camera/) by
Yihui Xie, author of [xaringan].


## &#x23F8;&#xFE0F; FreezeFrame

#### &#x1F4FA; [FreezeFrame Demo](https://pkg.garrickadenbuie.com/xaringanExtra/freezeframe/)

[freezeframejs]: http://ctrl-freaks.github.io/freezeframe.js/

FreezeFrame starts any gifs on a slide when you turn to that slide. This helps
alleviate the awkward pause that can happen when you turn to a slide
with a gif that has already started and you have to wait until it loops
back around. You can also directly click on the gif to stop or start it. Built using [freezeframe.js][freezeframejs].

To add FreezeFrame to your `xaringan` presentation, add the following
code chunk to your slides\' R Markdown file.

````markdown
```{r xaringanExtra-freezeframe, echo=FALSE}`r ''`
xaringanExtra::use_freezeframe()
```
````

| Argument | Description |
|:-|:-|
| selector | The selector used to search for `.gifs` to freeze. |
| trigger | The trigger event to start animation for non-touch devices. One of `"click"` (default), `"hover"` or `"none"`. |
| overlay | Whether or not to display a play icon on top of the paused image, default: `FALSE`. |
| responsive | Whether or not to make the image responsive (100% width), default: `TRUE`. |
| warnings | Whether or not to issue warnings in the browser console if an image doesn't appear to be a gif. |


## &#x1F4CB; Clipboard

#### &#x1F4FA; [Clipboard Demo](https://pkg.garrickadenbuie.com/xaringanExtra/clipboard/)

[clipboardjs]: https://clipboardjs.com/

Add a "Copy Code" button for one-click code chunk copying.

```{r child="man/fragments/clipboard-details.Rmd"}
```

clipboard works in xaringan slides, R Markdown documents, blogdown sites, and Shiny apps!

**Related projects:** For related R packages that provide copy support via [clipboard.js][clipboardjs] see

- [RLesur/klippy: Copy to Clipboard Buttons for RMarkdown HTML Documents](https://github.com/RLesur/klippy)
- [sbihorel/rclipboard: clipboard.js for R/Shiny Applications](https://github.com/sbihorel/rclipboard)

## &#x1F4D0; Fit to Screen

#### &#x1F4FA; [Fit to Screen Demo](https://pkg.garrickadenbuie.com/xaringanExtra/fit-screen/)

xaringan/remark slides scale at a consistent ratio when the browser window is resized.
In other words, if the slide ratio is `4:3`,
then remark scales the slides and positions them in the browser window
so that they maintain the aspect ratio.

In certain situations,
like when showing slides in split screen next to another window like RStudio,
this causes the slides to become rather small.
Alternatively,
it's a great way to be able to adapt your slides
to the aspect ratio of the projector or television screen
when you don't know the ratio ahead of time.

This extension adds a short cut key — <kbd>Alt</kbd>/<kbd>Option</kbd>+ <kbd>F</kbd> —
that fits the slides to the screen and ignores the slide ratio.
(Currently, it only turns on; reload your slides to return to normal.)

![](man/figures/fit-screen.gif)

````markdown
```{r xaringan-fit-screen, echo=FALSE}`r ''`
xaringanExtra::use_fit_screen()
```
````


## &#x1F60E; Extra Styles

#### &#x1F4FA; [Extra Styles Demo](https://pkg.garrickadenbuie.com/xaringanExtra/extra-styles/)

### Extra Styles

I've collected a few CSS extras that I like to include in my slides,
that I've bundled up into the `use_extra_styles()` function.

````markdown
```{r xaringan-extra-styles}`r ''`
xaringanExtra::use_extra_styles(
  hover_code_line = TRUE,         #<<
  mute_unhighlighted_code = TRUE  #<<
)
```
````

- `hover_code_line` adds a little floating triangle next to the hovered line in a code chunk

- `mute_unhighlighted_code` modifies the xaringan/remarkjs line highlighting to mute the lines that _aren't highlighted_.

![](man/figures/extra-styles-hover.gif)

### Progress Bar

You can also add an animated progress bar using `xaringanExtra::use_progress_bar()`.

````markdown
```{r xaringanExtra, echo = FALSE}`r ''`
xaringanExtra::use_progress_bar(color = "#0051BA", location = "top")
```
````

- `color` can be any CSS color

- `location` can be `"top"` or `"bottom"`

- `height` can be a valid CSS unit, e.g. `10px` or `0.25em`