# mask-image

> Applies a CSS mask image, or the given subset of mask properties when passed an options object.

```ts
import { mask } from "@sdxc/u/effects";
```

Applies a CSS mask image, or the given subset of mask properties when
passed an options object. Every property is mirrored onto its `-webkit-`
prefixed twin, which Safari requires to render an element mask.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.mask("linear-gradient(to bottom, transparent, black)")` | `css({ maskImage: "linear-gradient(to bottom, transparent, black)", WebkitMaskImage: "linear-gradient(to bottom, transparent, black)" })` |
| `u.mask({ image: "url(/badge.png)", size: "contain", position: "center", repeat: "no-repeat" })` | `css({ maskImage: "url(/badge.png)", WebkitMaskImage: "url(/badge.png)", maskSize: "contain", WebkitMaskSize: "contain", maskPosition: "center", WebkitMaskPosition: "center", maskRepeat: "no-repeat", WebkitMaskRepeat: "no-repeat" })` |

## Examples

### Basic example

Use `mask(image)` with a gradient or an image to hide an element where the mask is transparent:

```tsx
<img
	mix={[mask("linear-gradient(to bottom, black 40%, transparent)"), ...]}
	src={...}
	alt=""
/>
```

### Using a radial gradient

Any CSS image works as a mask, like a `radial-gradient()` that fades an image out from its centre:

```tsx
<img
	mix={[mask("radial-gradient(closest-side, black 50%, transparent)"), ...]}
	src={...}
	alt=""
/>
```

### Setting size and repeat

Pass an object to set the mask's `image`, `size`, `position`, `repeat` and `mode` together:

```tsx
<img
	mix={[
		mask({
			image: "radial-gradient(circle, black 45%, transparent 50%)",
			size: "0.75rem 0.75rem",
			repeat: "repeat",
		}),
		...,
	]}
	src={...}
	alt=""
/>
```

## Applying on a state

Wrap the call in a state utility to scope it to one selector.

```ts
u.hover(u.mask("linear-gradient(to bottom, transparent, black)"))
```

## Responsive design

Wrap the call in a container query to scope it to one width.

```ts
u.at("md", u.mask("linear-gradient(to bottom, transparent, black)"))
```

## Signature

```ts
u.mask(image: string)
```