Mask

The TechUI mask component (TuiMask) is a foundational element for building modals, drawers, and full-screen overlays. It is primarily used to block user interaction with the underlying interface and provide visual depth focus (usually combined with background blur or dimming effects).

Similar to the Loading component, the Mask component supports both Functional and Component-based invocation methods to adapt to different development scenarios.

Global Method Invocation

In business logic, if you need to temporarily create a mask (e.g., for custom popup logic), it is recommended to use the global method $tMask.

import { inject } from 'vue';

const { $tMask, $tMaskClose } = inject('$global');

const showMask = () => {
  $tMask({
    visible: true,
    appendTo: "#app",      // Specify mount node
    position: "fixed",     // Positioning mode
    zIndex: 2000,          // Custom z-index
    
    // Callback for clicking the mask
    click: () => {
      console.log("Mask clicked!");
      $tMaskClose(); // Close mask
    }
  });
};

Component Invocation

In Vue templates, it is usually used in conjunction with <transition> or business components (such as sidebars, custom panels).

<template>
  <div class="custom-panel-wrap" style="position: relative; height: 300px;">
    
    <div class="content">...</div>

    <TuiMask 
      :visible="showMask" 
      position="absolute"
      :modal="true"
      @click="handleMaskClick"
    />
  </div>
</template>

API Reference

TuiMask Props / $tMask Parameters

Property Name	Type	Default	Description
visible	Boolean	false	Controls the display and hiding of the mask.
appendTo	String / Object	null	Specifies the target DOM node to mount to (selector string or DOM object). Usually used to hoist the mask to body or a specific container level.
position	String	null	Positioning mode. Optional values: 'fixed' (relative to viewport), 'absolute' (relative to parent container).
modal	Boolean	true	Whether to enable the modal background (i.e., show dimmed or blurred background color). If false, the mask is transparent but still intercepts clicks.
zIndex	Number	-	Custom z-index.
click	Function	-	Callback function triggered when the user clicks the mask layer.
destroy	Function	-	(Internal use) Callback to destroy the component instance.
dynamicRender	Boolean	false	(Internal use) Marks whether it is in dynamic render mode.

Global Methods

• $tMask(options): Creates and displays a mask instance. The options parameter is the same as the property table above.
• $tMaskClose(): Closes and destroys the current mask instance created by the global method.

Best Practices

1. Positioning Strategy:
   • If you need a full-screen mask (blocking the entire page), please use position: 'fixed' and mount it to #tuiRoot or #app.
   • If you only need to obscure a specific card or area, please use position: 'absolute' and ensure the parent container has position: relative.
2. Interaction Lifecycle:
   • When using $tMask, make sure to call $tMaskClose() within the click callback or at the end of the business flow; otherwise, the mask will persist indefinitely.
3. Animation Integration:
   • TuiMask has integrated fade-in/fade-out transition animations internally, so there is no need to wrap it with an extra <transition> component.