Skip to content
On this page

useTitle

Category
Export Size
1.41 kB
Last Changed
2 months ago

Reactive document title.

TIP

When using with Nuxt 3, this functions will NOT be auto imported in favor of Nuxt's built-in useTitle(). Use explicit import if you want to use the function from VueUse.

Demo

Title

Usage

js
import { useTitle } from '@vueuse/core'

const title = useTitle()
console.log(title.value) // print current title
title.value = 'Hello' // change current title
import { useTitle } from '@vueuse/core'

const title = useTitle()
console.log(title.value) // print current title
title.value = 'Hello' // change current title

Set initial title immediately:

js
const title = useTitle('New Title')
const title = useTitle('New Title')

Pass a ref and the title will be updated when the source ref changes:

js
import { useTitle } from '@vueuse/core'

const messages = ref(0)

const title = computed(() => {
  return !messages.value ? 'No message' : `${messages.value} new messages`
})

useTitle(title) // document title will match with the ref "title"
import { useTitle } from '@vueuse/core'

const messages = ref(0)

const title = computed(() => {
  return !messages.value ? 'No message' : `${messages.value} new messages`
})

useTitle(title) // document title will match with the ref "title"

Pass an optional template tag Vue Meta Title Template to update the title to be injected into this template:

js
const title = useTitle('New Title', { titleTemplate: '%s | My Awesome Website' })
const title = useTitle('New Title', { titleTemplate: '%s | My Awesome Website' })

WARNING

observe is incompatible with titleTemplate.

Type Declarations

typescript
export declare type UseTitleOptionsBase =
  | {
      /**
       * Observe `document.title` changes using MutationObserve
       * Cannot be used together with `titleTemplate` option.
       *
       * @default false
       */
      observe?: boolean
    }
  | {
      /**
       * The template string to parse the title (e.g., '%s | My Website')
       * Cannot be used together with `observe` option.
       *
       * @default '%s'
       */
      titleTemplate?: MaybeRef<string> | ((title: string) => string)
    }
export declare type UseTitleOptions = ConfigurableDocument & UseTitleOptionsBase
export declare function useTitle(
  newTitle: MaybeReadonlyRef<string | null | undefined>,
  options?: UseTitleOptions
): ComputedRef<string | null | undefined>
export declare function useTitle(
  newTitle?: MaybeRef<string | null | undefined>,
  options?: UseTitleOptions
): Ref<string | null | undefined>
export declare type UseTitleReturn = ReturnType<typeof useTitle>
export declare type UseTitleOptionsBase =
  | {
      /**
       * Observe `document.title` changes using MutationObserve
       * Cannot be used together with `titleTemplate` option.
       *
       * @default false
       */
      observe?: boolean
    }
  | {
      /**
       * The template string to parse the title (e.g., '%s | My Website')
       * Cannot be used together with `observe` option.
       *
       * @default '%s'
       */
      titleTemplate?: MaybeRef<string> | ((title: string) => string)
    }
export declare type UseTitleOptions = ConfigurableDocument & UseTitleOptionsBase
export declare function useTitle(
  newTitle: MaybeReadonlyRef<string | null | undefined>,
  options?: UseTitleOptions
): ComputedRef<string | null | undefined>
export declare function useTitle(
  newTitle?: MaybeRef<string | null | undefined>,
  options?: UseTitleOptions
): Ref<string | null | undefined>
export declare type UseTitleReturn = ReturnType<typeof useTitle>

Source

SourceDemoDocs

Contributors

Anthony Fu
Alex Kozack
Antério Vieira
Levi (Nguyễn Lương Huy)
Preetesh Jain
Michael Roberts

Changelog

v9.3.1 on 10/17/2022
8c1ba - fix: prevent observe and titleTemplate been specified at the same time (#2049)
v8.9.1 on 7/8/2022
a9ccc - feat(all): use MaybeComputedRef (#1768)
v7.4.1 on 12/23/2021
357ac - feat: added optional titleTemplate injection

Released under the MIT License.