CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<c-loader>

A loading overlay that covers a container with a translucent scrim and a centred spinner, with an optional message below it, while that container's content loads.

Usage

Place the c-loader inside the container it should cover, and make that container a positioning context (position: relative): the loader fills the nearest positioned ancestor. It shows while it is in the page; bind hide to take it away. Toggling hide fades the loader out and back in, which removing it with v-if would skip.

<section style="position: relative">
  <c-loader :hide="!loading">Loading projects…</c-loader>
  …
</section>

When to use

  • Covering a region — a card, a panel, a list — while its content loads or refreshes, so it is not read or used half-updated.
  • For a small inline wait, use c-spinner; for known progress, c-progress-bar or c-progress-circle. c-data-table has its own loading state.

Message and spinner

Slot a short message to explain the wait. It fades in below the spinner after content-delay milliseconds (0 by default), so a delay keeps a quick load down to the spinner alone. size and thickness set the spinner's diameter and stroke in pixels (48 and 4 by default); the 3.x width still sets the stroke until 5.0, and thickness wins when both are set.

Accessibility

The scrim keeps the pointer off the covered content, but not the keyboard: Tab still reaches controls beneath it, so make the region inert while it loads where that matters. The loader adds no role, busy state or live region, and its message is read in place but not announced when it appears. Set aria-busy="true" on the covered region while it loads, and announce the outcome yourself where the user needs to hear it.

Customization

::part(root) is the overlay: the scrim, painted in the surface role at 80% opacity, and the primary text colour that the spinner takes. ::part(content) is the message.

c-loader::part(root) {
  color: var(--c-secondary);
}

Examples

Basic
Vue React Angular TypeScript
<template>
  <div style="display: grid; gap: 12px; justify-items: start">
    <c-button @click="loading = !loading">Toggle loader</c-button>

    <!-- The loader fills the nearest position: relative ancestor -->
    <div style="position: relative; height: 160px; width: 100%">
      <c-loader :hide="!loading" content-delay="1000">
        Loading resources
      </c-loader>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const loading = ref(true);
</script>

API reference

<c-loader>

A loading overlay that covers a container with a translucent scrim and a centred spinner, with an optional message below it, while that container's content loads.

Properties

PropertyAttributeTypeDefaultDescription
contentDelaycontent-delaynumber0 Delay, in milliseconds, before the slotted message fades in once the loader shows.
hidehidebooleanfalse Hide the loader. Toggling it fades the loader in and out, so keep the element mounted and bind `hide` rather than using `v-if`, which would unmount it and skip the fade-out.
sizesizenumber48 The spinner's diameter in pixels.
thicknessthicknessnumber— The spinner's stroke thickness in pixels: 4 unless set.
width deprecated widthnumber4 Deprecated. Use `thickness`. The spinner's stroke width in pixels.

Slots

SlotDescription
defaultMessage text revealed below the spinner after `content-delay`

CSS parts

Style from outside with c-loader::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe overlay covering the nearest positioned ancestor: the scrim, and the text colour the spinner takes
contentThe message wrapper anchored below the spinner