LazyLoader: Reloadable


	import Quickshell

Asynchronous component loader. More

Properties

Detailed Description

The LazyLoader can be used to prepare components that don’t need to be created immediately, such as windows that aren’t visible until triggered by another action. It works on creating the component in the gaps between frame rendering to prevent blocking the interface thread. It can also be used to preserve memory by loading components only when you need them and unloading them afterward.

Note that when reloading the UI due to changes, lazy loaders will always load synchronously so windows can be reused.

Example

The following example creates a PopupWindow asynchronously as the bar loads. This means the bar can be shown onscreen before the popup is ready, however trying to show the popup before it has finished loading in the background will cause the UI thread to block.

import QtQuick
import QtQuick.Controls
import Quickshell

ShellRoot {
  PanelWindow {
    id: window
    height: 50

    anchors {
      bottom: true
      left: true
      right: true
    }

    LazyLoader {
      id: popupLoader

      // start loading immediately
      loading: true

      // this window will be loaded in the background during spare
      // frame time unless active is set to true, where it will be
      // loaded in the foreground
      PopupWindow {
        // position the popup above the button
        parentWindow: window
        relativeX: window.width / 2 - width / 2
        relativeY: -height

        // some heavy component here

        width: 200
        height: 200
      }
    }

    Button {
      anchors.centerIn: parent
      text: "show popup"

      // accessing popupLoader.item will force the loader to
      // finish loading on the UI thread if it isn't finished yet.
      onClicked: popupLoader.item.visible = !popupLoader.item.visible
    }
  }
}

    
  

⚠️

Components that internally load other components must explicitly support asynchronous loading to avoid blocking.

Notably, Variants does not corrently support asynchronous loading, meaning using it inside a LazyLoader will block similarly to not having a loader to start with.

⚠️

LazyLoaders do not start loading before the first window is created, meaning if you create all windows inside of lazy loaders, none of them will ever load.

Property Details

active: bool

If the component is fully loaded.

Setting this property to true will force the component to load to completion, blocking the UI, and setting it to false will destroy the component, requiring it to be loaded again.