Skip to main content

​
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