Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pyncz/tailwind-mask-image

A `mask-image` plugin for TailwindCSS
https://github.com/pyncz/tailwind-mask-image

css css-utils mask-image plugin tailwind tailwindcss

Last synced: about 4 hours ago
JSON representation

A `mask-image` plugin for TailwindCSS

Awesome Lists containing this project

README 

        
# @pyncz/tailwind-mask-image



A `mask-image` plugin for [Tailwind CSS](https://tailwindcss.com).



[View on Tailwind Play](https://play.tailwindcss.com/szgRchW420)



---



# Install



Install the package with your preferred package-manager.

```

pnpm install @pyncz/tailwind-mask-image

```



After that, simply add the plugin into your `tailwind.config.js`:



```js

// tailwind.config.js

module.exports = {

  // ...

  plugins: [

    // ...

    require('@pyncz/tailwind-mask-image')

  ],

}

```



# Usage



## mask-image



There are 3 default values the `mask` utility can accept:

- `linear`

- `radial`

- `none`



### `linear`



Applies a `linear-gradient` as the mask image. Opacity is set from 100% at the start to 0% at the end, by default.



```html



```

![mask-linear example](examples/mask-linear.png)



#### Direction `mask-dir`



By default, the gradient is [directed](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient#values) to bottom. You can easily customize the direction with `mask-dir` utility, including arbitrary values.



```html







```

![mask-dir example](examples/mask-dir.png)



#### Opacity Stops



The `stops` API is similar to tailwind's [Gradient Color Stops](https://tailwindcss.com/docs/gradient-color-stops) core utils, so you can customize your linear mask in a familiar way.



**But!** An important difference is that here you should use not `colors` but `opacity` values.



The `opacity` values are taken from your theme specified in the `tailwind.config.js`, but you obviously can use arbitrary opacity values as well.



```html







```

![mask-linear stops' example](examples/mask-linear-stops.png)



> **Note**

> You don't have to specify **all** the stops, because the default values (100% for the start and 0% for the end point) still work.



##### Stops positions



In addition to setting the opacity of the stops, you can also set the **position** using `mask-point`.



```html





```

![stops' points example](examples/mask-linear-stops-points.png)



This utility don't accept any default value, so use arbitrary values.



### `radial`



Applies a `radial-gradient` as the mask image. Like for the `mask-linear` util, the gradient is spread from 100% opacity at the center to 0% at the ending shape.



```html



```

![mask-radial example](examples/mask-radial.png)



#### Shape `mask-shape`



[Shape](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/radial-gradient#values) of the gradient, `ellipse` (by default) or `circle`.



```html





```

![mask-shape example](examples/mask-shape.png)



#### Position `mask-at`



By default, the gradient's position is `center`. You can use the same values as for the [`background-position` css prop](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position#syntax) (`top`, `bottom left` etc), as well as arbitrary values with explicit position.



```html



```

![mask-at example](examples/mask-at.png)



#### Reach `mask-reach`



With this util you can specify the size of the gradient.



```html









```

![mask-reach example](examples/mask-reach.png)



Besides *as-they-are* keyword-values, there are also a couple of aliases:

- `mask-reach-contain` for `closest-side`

- `mask-reach-cover` for `farthest-corner`



You can also use arbitrary values:



```html





```

![example for mask-reach with arbitrary values](examples/mask-reach-arbitrary.png)



#### Stops



> **Note**

> The opacity stops for `mask-radial` are the same as [the ones described for `mask-linear`](#opacity-stops), including [points API](#stops-positions).



```html







```

![mask-radial stops' example](examples/mask-radial-stops.png)



### `none`



This value matches `mask-image` css prop's default value so it makes no sense to use it *separately*, but it may be pretty useful if you apply the mask responsively.



```html



```

![mask-none example](examples/mask-none.png)



### Arbitrary values



#### Images



The `mask-image` css prop accepts not only gradients but images as well. You can use arbitrary values, for example, to apply `url()` as the mask image.



```html



```

![arbitrary mask image example](examples/arbitrary-image.png)



#### Gradients



You can pass other types of the gradients, e.g. `conic-gradient` etc.



```html



```

![arbitrary conic-gradient mask example](examples/arbitrary-conic-gradient.png)



Also, you may want not to use the API above even for `linear-gradient` or `radial-gradient` so you can pass them arbitrarily too.



```html



```



## mask-size



```html







```

![mask size example](examples/mask-size.png)



## mask-position



```html







```

![mask position example](examples/mask-position.png)



## mask-repeat



You can manage the [`mask-repeat` css property](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-repeat) as well with the following utilities:

- `mask-repeat`

- `mask-repeat-x`

- `mask-repeat-y`

- `mask-repeat-space`

- `mask-repeat-round`

- `mask-no-repeat`



```html





```

![mask-repeat example](examples/mask-repeat.png)