useLoadingIndicator

This composable gives you access to the loading state of the app page.

Description

A composable which returns the loading state of the page. Used by <NuxtLoadingIndicator> and controllable. It hooks into page:loading:start and page:loading:end to change its state.

Parameters

options · object

Configuration options for the loading indicator.

duration · number · default: "2000"

Duration of the loading bar, in milliseconds.

throttle · number · default: "200"

Throttle the appearing and hiding, in milliseconds.

estimatedProgress · (duration: number, elapsed: number) => number

By default Nuxt will back off as it approaches 100%. You can provide a custom function to customize the progress estimation, which is a function that receives the duration of the loading bar (above) and the elapsed time. It should return a value between 0 and 100.

Return Values

isLoading · Ref<boolean>

The loading state.

error · Ref<boolean>

The error state.

progress · Ref<number>

The progress state. From 0 to 100.

start · (opts?: { force?: boolean }) => void

Set isLoading to true and start to increase the progress value. start accepts a { force: true } option to skip the interval and show the loading state immediately.

set · (value: number, opts?: { force?: boolean }) => void

Set the progress value to a specific value. set accepts a { force: true } option to skip the interval and show the loading state immediately.

finish · (opts?: { force?: boolean, error?: boolean }) => void

Set the progress value to 100, stop all timers and intervals then reset the loading state 500 ms later. finish accepts a { force: true } option to skip the interval before the state is reset, and { error: true } to change the loading bar color and set the error property to true.

clear · () => void

Used by finish(). Clear all timers and intervals used by the composable.

Examples

Basic Usage

<script setup lang="ts">
const { progress, isLoading, start, finish, clear } = useLoadingIndicator({
  duration: 2000,
  throttle: 200,
  // This is how progress is calculated by default
  estimatedProgress: (duration, elapsed) => (2 / Math.PI * 100) * Math.atan(elapsed / duration * 100 / 50),
})
</script>

Force Start

<script setup lang="ts">
const { start, set } = useLoadingIndicator()
// same as set(0, { force: true })
// set the progress to 0, and show loading immediately
start({ force: true })
</script>

Type

interface LoadingIndicatorOpts {
  duration?: number
  throttle?: number
  estimatedProgress?: (duration: number, elapsed: number) => number
}

interface LoadingIndicator {
  isLoading: Ref<boolean>
  error: Ref<boolean>
  progress: Ref<number>
  start: (opts?: { force?: boolean }) => void
  set: (value: number, opts?: { force?: boolean }) => void
  finish: (opts?: { force?: boolean, error?: boolean }) => void
  clear: () => void
}

export function useLoadingIndicator (
  opts?: LoadingIndicatorOpts
): LoadingIndicator