Accessibility: Full

Translations: Not Needed

Loading Bar

Loading Bar component for displaying loading progress at the top of the page or within a container

Basic Usage

Wrap content in HLLoadingBar and call the exposed startLoadBar, stopLoadBar, and errorLoadBar methods via a ref to control the loading bar.

INFO

With no to prop the bar mounts to body, so it appears as a thin line across the very top of the browser viewport — not above the buttons below. Scroll to the top of the page before pressing Start, or the bar can be out of view. The bar is only rendered while a load is in progress; when idle it isn't in the DOM at all.

To place the bar inside a container instead, see Custom Position.

vue

<template>
  <HLLoadingBar ref="loadingBarRef">
    <div style="padding: 20px;">
      <HLButton color="blue" variant="primary" @click="handleStart">
        Start Loading
      </HLButton>
      <HLButton @click="handleFinish">
        Finish Loading
      </HLButton>
      <HLButton color="red" variant="primary" @click="handleError">
        Error
      </HLButton>
    </div>
  </HLLoadingBar>
</template>

<script setup lang="ts">
  import { HLLoadingBar, HLButton } from '@platform-ui/highrise'
  import { ref } from 'vue'

  const loadingBarRef = ref(null)

  const handleStart = () => {
    loadingBarRef.value?.startLoadBar()
  }

  const handleFinish = () => {
    loadingBarRef.value?.stopLoadBar()
  }

  const handleError = () => {
    loadingBarRef.value?.errorLoadBar()
  }
</script>

Custom Position

Mount the loading bar inside a specific container with the to prop instead of letting it default to the top of the viewport. Pass the container element and give it position: relative, then set position: absolute via containerStyle so the bar is placed within that container.

vue

<template>
  <!-- The container needs `position: relative` so the bar is placed inside it -->
  <div ref="customBoxRef" style="height: 200px; width: 100%; border: 2px solid #e5e7eb; position: relative;">
    <HLLoadingBar ref="customLoadingBarRef" :to="customBoxRef" :containerStyle="{ position: 'absolute' }"> </HLLoadingBar>
  </div>
  <div>
    <HLButton color="blue" variant="primary" @click="handleCustomStart">
      Start Loading
    </HLButton>
    <HLButton @click="handleCustomFinish">
      Finish Loading
    </HLButton>
    <HLButton color="red" variant="primary" @click="handleCustomError">
      Error
    </HLButton>
  </div>
</template>

<script setup lang="ts">
  import { HLLoadingBar, HLButton } from '@platform-ui/highrise'
  import { ref } from 'vue'

  const customBoxRef = ref(null)
  const customLoadingBarRef = ref(null)

  const handleCustomStart = () => {
    customLoadingBarRef.value?.startLoadBar()
  }

  const handleCustomFinish = () => {
    customLoadingBarRef.value?.stopLoadBar()
  }

  const handleCustomError = () => {
    customLoadingBarRef.value?.errorLoadBar()
  }
</script>

Targeting a Container by Selector

to also accepts a CSS selector string, which is handy when the target isn't easy to reach with a template ref — for example an element rendered by a parent layout.

The target is resolved once, when the loading bar mounts. If no element matches at that moment the bar never renders — it does not fall back to body, and no warning is logged. Creating the element later doesn't help, so prefer a template ref whenever the target is rendered by the same component.

vue

<template>
  <!-- The target needs `position: relative` so the bar is placed inside it -->
  <div id="loading-bar-target" style="position: relative; height: 200px;"></div>

  <HLLoadingBar ref="loadingBarRef" to="#loading-bar-target" :containerStyle="{ position: 'absolute' }" />
</template>

<script setup lang="ts">
import { HLLoadingBar } from '@platform-ui/highrise'
import { ref } from 'vue'

const loadingBarRef = ref(null)
</script>

Custom Bar Styling

loadingBarStyle restyles the bar itself, with separate entries for the loading and error states — use it to change the bar's colour and thickness. Press Error below to see the error style.

To style the bar's container rather than the bar, use containerStyle, or containerClass when the styling is reusable and belongs in a stylesheet.

vue

<template>
  <div ref="boxRef" style="height: 200px; width: 100%; border: 2px solid #e5e7eb; position: relative;">
    <HLLoadingBar
      ref="loadingBarRef"
      :to="boxRef"
      containerClass="demo-loading-bar-container"
      :containerStyle="{ position: 'absolute' }"
      :loadingBarStyle="{
        loading: { backgroundColor: '#f97316', height: '6px' },
        error: { backgroundColor: '#ef4444', height: '6px' }
      }"
    >
    </HLLoadingBar>
  </div>
  <div>
    <HLButton color="blue" variant="primary" @click="handleStart">Start Loading</HLButton>
    <HLButton @click="handleFinish">Finish Loading</HLButton>
    <HLButton color="red" variant="primary" @click="handleError">Error</HLButton>
  </div>
</template>

<script setup lang="ts">
import { HLLoadingBar, HLButton } from '@platform-ui/highrise'
import { ref } from 'vue'

const boxRef = ref(null)
const loadingBarRef = ref(null)

const handleStart = () => {
  loadingBarRef.value?.startLoadBar()
}

const handleFinish = () => {
  loadingBarRef.value?.stopLoadBar()
}

const handleError = () => {
  loadingBarRef.value?.errorLoadBar()
}
</script>

<style>
/* containerClass — reusable container styling kept out of the template */
.demo-loading-bar-container {
  opacity: 0.85;
}
</style>

Accessibility

The loading bar provides visual feedback for loading states
Use in conjunction with aria-busy or aria-live regions to announce loading states to screen readers
Consider adding descriptive text or announcements for users who may not perceive the visual loading indicator

Imports

import { HLLoadingBar } from '@platform-ui/highrise'

Props

Name	Type	Default	Description
containerClass	`string \| undefined`	`undefined`	Class name for the loading bar container
containerStyle	`string \| CSSProperties \| undefined`	`undefined`	Style for the loading bar container. Use `position: absolute` when mounting into a container.
loadingBarStyle	`LoadingBarStyle \| undefined`	`undefined`	Custom styles for the bar itself, per state (loading / error)
to	`string \| HTMLElement \| false \| undefined`	`undefined`	Where to mount the loading bar: a CSS selector, an element, or `false` to render inline without teleporting. When unset the bar mounts to `body`, appearing at the top of the viewport.

Types

LoadingBarStyle

interface LoadingBarStyle {
  loading?: string | CSSProperties | undefined
  error?: string | CSSProperties | undefined
}

Slots

Name	Parameters	Description
`default`	`undefined`	Content to wrap with the loading bar provider

Methods

Name	Parameters	Description
`startLoadBar`	`()`	Starts the loading bar animation
`stopLoadBar`	`()`	Completes the loading bar animation
`errorLoadBar`	`()`	Shows the loading bar in error state

Loading Bar ​

Basic Usage ​

Custom Position ​

Targeting a Container by Selector ​

Custom Bar Styling ​

Accessibility ​

Imports ​

Props ​

Types ​

LoadingBarStyle ​

Slots ​

Methods ​