Directive

The directive provides a click trigger without requiring a model value.

Trigger and fullscreen target

The element with v-fullscreen is the click trigger; target selects the fullscreen element. If no target is specified, the directive controls document.body.

Playground

Edit this example

Loading example…

<script setup>
import { ref } from 'vue'
import { vFullscreen } from 'vue-fullscreen'

const isFullscreen = ref(false)
const options = {
  target: '#panel',
  pageOnly: false,
  teleport: true,
  callback: (value) => {
    isFullscreen.value = value
  },
}

function report(error) {
  isFullscreen.value = false
  console.error(error)
}
</script>

<template>
  <div>
    <button
      :disabled="isFullscreen"
      v-fullscreen="options"
      @fullscreen-error="report($event.detail)"
    >
      Enter fullscreen
    </button>
    <section id="panel">
      <button
        v-if="isFullscreen"
        v-fullscreen="options"
        @fullscreen-error="report($event.detail)"
      >
        Exit fullscreen
      </button>
      <!-- Your fullscreen content -->
    </section>
  </div>
</template>

With a regular setup() function or the Options API, register the directive locally in the component’s directives option as fullscreen: vFullscreen.

Binding values

<!-- No binding: target document.body -->
<button v-fullscreen>Fullscreen page</button>

<!-- The button triggers fullscreen for #report, rather than for itself. -->
<button v-fullscreen="'#report'">Fullscreen report</button>
<section id="report">
  Report content
  <button v-fullscreen="'#report'">Exit fullscreen</button>
</section>

<!-- Target and options -->
<button v-fullscreen="{ target: '#report', pageOnly: true, teleport: true }">
  Page-only fullscreen
</button>

The binding object also accepts fullscreenClass and callback(isFullscreen). Bind the same directive inside the target to provide an exit button. Unmounting the directive that started the session cleans it up automatically.

Modifiers

.pageOnly and .teleport set the corresponding options. Explicit object values take precedence over modifiers. For example, .pageOnly="{ pageOnly: false }" requests native mode.

Targets

Set target in the binding object to select the fullscreen element:

Target type	Example
HTML element	{ target: document.getElementById('panel') }
Vue ref object	{ target: panelRef }
Component instance	{ target: panelComponent }; uses its $el
id string	{ target: 'panel' } or { target: '#panel' }
CSS selector	{ target: '.panel' }
Getter	{ target: () => document.getElementById('panel') }

Strings are resolved by id first (with an optional # prefix), then as CSS selectors. An id takes priority when both match. The current target is resolved on each entry.

Omitting the target or passing null directly uses document.body. Missing selectors, unmounted refs and other unresolved targets dispatch fullscreen-error.

The shorthands v-fullscreen="'panel'", v-fullscreen="'#panel'" and v-fullscreen="'.panel'" follow the same resolution rule.

Options

interface DirectiveOptions extends ApiOptions {
  target?: FullscreenTarget
}

Option	Type	Default	Purpose
target	FullscreenTarget	document.body	Accepted types: see Targets
pageOnly	boolean	false	Use page-only mode
teleport	boolean	false	Move to the body; disabled for a body target
fullscreenClass	string	'fullscreen'	Class to add while active
callback	(isFullscreen: boolean) => void	None	Report changes in state

Callbacks

Use callback to keep application state synchronized when fullscreen changes.

const options = {
  callback(isFullscreen) {
    console.log(isFullscreen)
  },
}

Error events

Failures dispatch a bubbling native fullscreen-error event. The error is in event.detail.

button.addEventListener('fullscreen-error', (event) => {
  console.error(event.detail)
})

A button outside the fullscreen target may not be visible in native mode. Put an exit button inside the target, or use Esc.