Native Mask Support in Tailwind CSS

[al-imam]

Currently, Tailwind CSS lacks native support for the mask property, leading me to create a plugin to address this gap. I believe that integrating a dedicated utility for mask directly into Tailwind CSS would enhance the framework's flexibility and improve the developer experience.

I propose the addition of a core mask utility in Tailwind CSS that allows developers to easily apply mask to elements using the mask property. This utility should cover essential options along with directional and granular control for more advanced use cases.

Plugin Implementation

I've tested this utility in various scenarios for my personal project, and it has proven to be a valuable addition. It covers basic use cases, including fading effects, which are common in many projects. However, I understand that a standardized approach in Tailwind CSS would ensure consistency and provide a solution for a wider range of projects.

 plugin(({ addComponents, matchUtilities, addUtilities }) => {
      const mask = [".mask", ".mask-x", ".mask-y", ".mask-top", ".mask-bottom", ".mask-right", ".mask-left"];

      addComponents({
        [mask]: {
          "--fade": "2rem",
          "--fade-x": "var(--fade)",
          "--fade-y": "var(--fade)",
          "--fade-top": "var(--fade-y)",
          "--fade-bottom": "var(--fade-y)",
          "--fade-left": "var(--fade-x)",
          "--fade-right": "var(--fade-x)",

          "--fade-g": "0px",
          "--fade-g-x": "var(--fade-g)",
          "--fade-g-y": "var(--fade-g)",
          "--fade-g-top": "var(--fade-g-y)",
          "--fade-g-bottom": "var(--fade-g-y)",
          "--fade-g-left": "var(--fade-g-x)",
          "--fade-g-right": "var(--fade-g-x)",

          "--alpha": "rgb(0 0 0 / 0)",
          "--solid": "rgb(0 0 0 / 1)",

          "--mask": `linear-gradient(180deg, 
            var(--alpha) calc(min(var(--fade-g-top), var(--fade-top))),
            var(--solid) var(--fade-top),
            var(--solid) calc(100% - var(--fade-bottom)),
            var(--alpha) calc(100% - calc(min(var(--fade-g-bottom), var(--fade-bottom))))
          ), 
          linear-gradient(90deg,
            var(--alpha) calc(min(var(--fade-g-left), var(--fade-left))),
            var(--solid) var(--fade-left),
            var(--solid) calc(100% - var(--fade-right)),
            var(--alpha) calc(100% - calc(min(var(--fade-g-right), var(--fade-right))))
          )`,
        },

        [`:is(${mask.join(", ")}):not(.mask-only)`]: {
          maskComposite: "intersect",
          maskImage: "var(--mask)",
        },

        ".mask-only": {},
      });

      addUtilities({
        ".mask-x": {
          "--fade-y": "0px",
        },

        ".mask-y": {
          "--fade-x": "0px",
        },

        ".mask-top": {
          "--fade-bottom": "0px",
          "--fade-left": "0px",
          "--fade-right": "0px",
        },

        ".mask-bottom": {
          "--fade-top": "0px",
          "--fade-left": "0px",
          "--fade-right": "0px",
        },

        ".mask-right": {
          "--fade-top": "0px",
          "--fade-left": "0px",
          "--fade-bottom": "0px",
        },

        ".mask-left": {
          "--fade-top": "0px",
          "--fade-right": "0px",
          "--fade-bottom": "0px",
        },
      });

      matchUtilities(
        {
          mask: value => ({
            "--fade": value,
          }),

          "mask-x": value => ({
            "--fade-x": value,
          }),

          "mask-y": value => ({
            "--fade-y": value,
          }),

          "mask-top": value => ({
            "--fade-top": value,
          }),

          "mask-bottom": value => ({
            "--fade-bottom": value,
          }),

          "mask-left": value => ({
            "--fade-left": value,
          }),

          "mask-right": value => ({
            "--fade-right": value,
          }),
        },
        {
          values: { ...defaultTheme.spacing, none: "0px" },
        }
      );

      matchUtilities(
        {
          "mask-g": value => ({
            "--fade-g": value,
          }),

          "mask-g-x": value => ({
            "--fade-g-x": value,
          }),

          "mask-g-y": value => ({
            "--fade-g-y": value,
          }),

          "mask-g-top": value => ({
            "--fade-g-top": value,
          }),

          "mask-g-bottom": value => ({
            "--fade-g-bottom": value,
          }),

          "mask-g-left": value => ({
            "--fade-left": value,
          }),

          "mask-g-right": value => ({
            "--fade-g-right": value,
          }),
        },
        {
          values: defaultTheme.spacing,
        }
      );

      matchUtilities(
        {
          "mask-alpha": value => ({
            "--alpha": `rgb(0 0 0 / ${value})`,
          }),

          "mask-solid": value => ({
            "--solid": `rgb(0 0 0 / ${value})`,
          }),
        },
        {
          values: defaultTheme.opacity,
        }
      );
    })

Basic Example

<div class="mask" /> <!-- default 2rem faded mask applied to all sides -->
<div class="mask mask-only [mask:var(--mask)_advance_customization]" />
<div class="mask-x mask-x-16 mask-g-x-4" />

As a junior developer, I value constructive feedback immensely. Please share your thoughts, suggestions, or concerns related to the addition of the mask utility in Tailwind CSS. Your input means a lot to me.