# Video

A GraphicBlock-wrapped HTML5 video with title, description and notes, plus optional play-when-in-view, poster and custom controls.

**Category:** Components/Multimedia/Video

**Import:** `import { Video } from '@reuters-graphics/graphics-components'`

## Props

| Prop | Type | Default | Required | Description |
|------|------|---------|:--------:|-------------|
| `src` | `string` | — | ✓ | Video source |
| `poster` | `string` | `''` |  | Image to be shown while the video is downloading |
| `ariaDescription` | `string` | — | ✓ | ARIA description, passed in as a markdown string. |
| `class` | `string` | `''` |  | Add extra classes to the block tag to target it with custom CSS. |
| `title` | `string` | — |  | Title of the graphic |
| `notes` | `string \| Snippet` | — |  | Notes to the graphic, passed in as a markdown string OR a custom snippet. |
| `description` | `string` | — |  | Description of the graphic, passed in as a markdown string. |
| `width` | `ContainerWidth` | `'normal'` |  | Width of the block within the article well. |
| `textWidth` | `ContainerWidth` | `'normal'` |  | Set a different width for the text within the text well, for example, "normal" to keep the title, description and notes inline with the rest of the text well. Can't ever be wider than `width`. |
| `preloadVideo` | `'auto' \| 'none' \| 'metadata'` | `'auto'` |  | Preload options. `auto` is ignored if `autoplay` is true. Can also be `none` or `metadata`. |
| `loopVideo` | `boolean` | `false` |  | Whether the video should loop. |
| `muteVideo` | `boolean` | `true` |  | Whether video should have sound or not. |
| `soundAutoplay` | `boolean` | `false` |  | If `true`, this allow videos with sound to autoplay if the user has previously interacted with DOM |
| `playVideoWhenInView` | `boolean` | `true` |  | Whether the video should play when it comes into view or just on page load |
| `playVideoThreshold` | `number` | `0.5` |  | Controls how much of the video should be visible when it starts playing. This is a number between 0 and 1, where 0 means the video will start playing as soon as its top enters the viewport, and 1 means it will start when the whole video is in the viewport. |
| `possibleToPlayPause` | `boolean` | `true` |  | Whether to have the option to pause and play video |
| `showControls` | `boolean` | `true` |  | Whether to show the play / pause buttons |
| `separateReplayIcon` | `boolean` | `false` |  | Whether to use a separate replay icon or use the play icon for replay as well |
| `controlsColour` | `string` | `'#333'` |  | Change the colour of the play/pause button |
| `controlsOpacityMin` | `number` | `0` |  | Change the minimum opacity of the play/pause button, which you see on mouseover. Must be between 0 and 1. |
| `controlsOpacityMax` | `number` | `0.7` |  | Change the maximum opacity of the play/pause button, which you see on mouseout. Must be between 0 and 1. |
| `controlsPosition` | `ControlsPosition` | `'top left'` |  | Have four options for controls position - top right, top left, bottom right, bottom left |
| `controlsBorderOffset` | `number` | `10` |  | Offset for the controls from the border |

## Examples

### Demo

```svelte
<Video
  ariaDescription="Required description of your video for screen readers."
  src={/* SilentVideo */}
  width="wide"
  notes="Optional caption for your video."
/>
```

### Autoplay controls

```svelte
<Video
  ariaDescription="Required description of your video for screen readers."
  src={/* SilentVideo */}
  loopVideo={true}
  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
  playVideoThreshold={0.9}
/>
```

### Audio controls

```svelte
<Video
  ariaDescription="Required description of your video for screen readers."
  src={/* SoundVideo */}
  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
  controlsColour="#152a1c"
  controlsOpacityMax={1}
  controlsOpacityMin={0.5}
  playVideoThreshold={0.9}
  muteVideo={false}
  soundAutoplay={true}
/>
```

### Controls

```svelte
<Video
  ariaDescription="Required description of your video for screen readers."
  src={/* SilentVideo */}
  width="normal"
  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
  playVideoThreshold={0.9}
  controlsColour="white"
  controlsOpacityMax={1}
  controlsOpacityMin={0.5}
  controlsPosition="bottom right"
  separateReplayIcon={true}
  loopVideo={false}
  soundAutoplay={true}
/>
```

### Text elements

```svelte
<Video
  src={SilentVideo}
  ariaDescription="Required description of your video for screen readers."
  title="Title for your video"
  description="Description for your video"
>
  {#snippet notes()}
    <aside>
      <p class="notes">Custom-styled notes for the video.</p>
    </aside>
  {/snippet}
</Video>
```

## Documentation

# Video

The `Video` component adds a video with various controls to your page such as:

- Play/pause button
- Autoplay controls, i.e. whether the video plays when it comes into view or on page load
- Looping
- Audio controls
- Text elements such as notes and titles

```svelte
<script>
  import { Video } from '@reuters-graphics/graphics-components';
</script>

<Video
  ariaDescription="Required description of your video for screen readers."
  src="my-video.mp4"
  width="wide"
  notes="Optional caption for your video."
/>
```

## Using with ArchieML docs

With the graphics kit, you'll likely get your text value from an ArchieML doc...

```yaml
# ArchieML doc
[blocks]
type: video
src: videos/my-video.mp4
width: wide
ariaDescription: Required description of your video for screen readers.
notes: Optional caption for your video.
loopVideo: true
[]
```

... which you'll parse out of a ArchieML block object before passing to the `Video` component.

```svelte
<!-- App.svelte -->
<script>
  import { Video } from '@reuters-graphics/graphics-components';
  import { asset } from '$app/paths'; // 👈 If using in the graphics kit...
  import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
</script>

{#each content.blocks as block}
  {#if block.type === 'video'}
    <Video
      ariaDescription={block.ariaDescription}
      src={asset(`/${block.src}`)}
      width={block.width}
      loopVideo={truthy(block.loopVideo)}
      notes={block.notes}
    />
  {/if}
{/each}
```

> **Note:** Some props, like `loopVideo`, expect boolean values. If you're using the graphics kit, you can use the `truthy()` util function to convert a string value to a boolean.

## Autoplay controls

By default, the video starts playing when 50% (0.5) of the video element's height comes into view. Adjust this with `playVideoThreshold`, which is a value between 0 and 1, where 0 means the video will start playing as soon as its top enters the viewport, and 1 means it will start when the whole video is in the viewport.

To make the video play on page load regardless of whether it is in view, set the prop `playVideoWhenInView` to `false`.

```svelte
<script>
  import { Video } from '@reuters-graphics/graphics-components';
</script>

<Video
  ariaDescription="Required description of your video for screen readers."
  src="https://..."
  loopVideo={true}
  playVideoThreshold={0.9}
  notes="World's longest glass bridge opens to public in Vietnam. (c) 2022 Thomson Reuters"
/>
```

## Audio controls

On most browsers, [autoplaying videos with sound](https://developer.chrome.com/blog/autoplay#:~:text=Muted%20autoplay%20is%20always%20allowed,to%20allow%20autoplay%20with%20sound.) is allowed only if the user has interacted with the page. (Autoplay is allowed with muted videos.)

By default, this component will not autoplay videos with sound. To change this, set `soundAutoplay` to `true`. This will allow the video to autoplay with sound when it comes into view, but only if the user has already interacted with the page by clicking or tapping on it.

Test this with the example below: the video will autoplay when it comes into view _only if_ you have clicked or tapped on the page before scrolling down to it.

```svelte
<script>
  import { Video } from '@reuters-graphics/graphics-components';
</script>

<Video
  ariaDescription="Required description of your video for screen readers."
  src="https://..."
  controlsColour="#152a1c"
  controlsOpacityMax={1}
  controlsOpacityMin={0.5}
  muteVideo={false}
  soundAutoplay={true}
/>
```

## Adding text

The `Video` component allows you to add a title, description and notes to your video, which are rendered by the `GraphicBlock` component.

Customise the `notes` section by passing a [snippet](https://svelte.dev/docs/svelte/snippet) instead of a string.

```svelte
<script>
  import { Video } from '@reuters-graphics/graphics-components';
</script>

<Video
  src="https://..."
  ariaDescription="Required description of your video for screen readers."
  title="Title for your video"
  description="Description for your video"
>
  <!-- Custom notes snippet -->
  {#snippet notes()}
    <aside>
      <p class="notes">Custom-styled notes for the video.</p>
    </aside>
  {/snippet}
</Video>

<style lang="scss">
  @use '@reuters-graphics/graphics-components/dist/scss/mixins' as mixins;

  p.notes {
    @include mixins.body-note;
  }
</style>
```