{"id":20652520,"url":"https://github.com/pyncz/tailwind-mask-image","last_synced_at":"2025-04-18T20:30:14.012Z","repository":{"id":143584912,"uuid":"616154733","full_name":"pyncz/tailwind-mask-image","owner":"pyncz","description":"A `mask-image` plugin for TailwindCSS","archived":false,"fork":false,"pushed_at":"2023-11-27T10:26:54.000Z","size":1220,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-14T10:37:09.420Z","etag":null,"topics":["css","css-utils","mask-image","plugin","tailwind","tailwindcss"],"latest_commit_sha":null,"homepage":"https://play.tailwindcss.com/szgRchW420","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyncz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-19T19:05:26.000Z","updated_at":"2024-04-14T08:24:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"a15d1896-be50-4c9f-894a-a4ea884219af","html_url":"https://github.com/pyncz/tailwind-mask-image","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyncz%2Ftailwind-mask-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyncz%2Ftailwind-mask-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyncz%2Ftailwind-mask-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyncz%2Ftailwind-mask-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyncz","download_url":"https://codeload.github.com/pyncz/tailwind-mask-image/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249543296,"owners_count":21288703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","css-utils","mask-image","plugin","tailwind","tailwindcss"],"created_at":"2024-11-16T17:35:26.585Z","updated_at":"2025-04-18T20:30:13.999Z","avatar_url":"https://github.com/pyncz.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003e [!WARNING]\n\u003e **🚧 Deprecated**\n\u003e\n\u003e `tailwindcss` added support for mask utils starting from v4.1! Feel free to use this plugin with earlier versions (tested with v3.x), but tbh, migration to v4.1 is the way to go.\n\u003e\n\u003e [See docs](https://tailwindcss.com/docs/mask-image) ⋅ [See blog post](https://tailwindcss.com/blog/tailwindcss-v4-1#mask-elements-with-the-mask-utilities)\n\n# @pyncz/tailwind-mask-image\n\nA `mask-image` plugin for [Tailwind CSS](https://tailwindcss.com).\n\n[\u003cimg alt=\"View on Tailwind Play\" src=\"https://img.shields.io/badge/View%20on%20Tailwind%20Play-%2357a7e1.svg?logo=tailwindcss\u0026logoColor=white\u0026style=flat-square\" /\u003e](https://play.tailwindcss.com/szgRchW420)\n\n---\n\n# Install\n\nInstall the package with your preferred package-manager.\n```\npnpm install @pyncz/tailwind-mask-image\n```\n\nAfter that, simply add the plugin into your `tailwind.config.js`:\n\n```js\n// tailwind.config.js\nmodule.exports = {\n  // ...\n  plugins: [\n    // ...\n    require('@pyncz/tailwind-mask-image')\n  ],\n}\n```\n\n\n# Usage\n\n## mask-image\n\nThere are 3 default values the `mask` utility can accept:\n- `linear`\n- `radial`\n- `none`\n\n\n### `linear`\n\nApplies a `linear-gradient` as the mask image. Opacity is set from 100% at the start to 0% at the end, by default.\n\n```html\n\u003cdiv class=\"mask-linear\" /\u003e\n```\n![mask-linear example](examples/mask-linear.png)\n\n#### Direction `mask-dir`\n\nBy 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.\n\n```html\n\u003cdiv class=\"mask-linear mask-dir-to-t\" /\u003e\n\u003cdiv class=\"mask-linear mask-dir-to-tl\" /\u003e\n\u003cdiv class=\"mask-linear mask-dir-[10deg]\" /\u003e\n```\n![mask-dir example](examples/mask-dir.png)\n\n#### Opacity Stops\n\nThe `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.\n\n**But!** An important difference is that here you should use not `colors` but `opacity` values.\n\nThe `opacity` values are taken from your theme specified in the `tailwind.config.js`, but you obviously can use arbitrary opacity values as well.\n\n```html\n\u003cdiv class=\"mask-linear mask-from-50 mask-to-[0.1]\" /\u003e\n\u003cdiv class=\"mask-linear mask-from-0 mask-via-20\" /\u003e\n\u003cdiv class=\"mask-linear mask-from-0 mask-via-100 mask-to-50\" /\u003e\n```\n![mask-linear stops' example](examples/mask-linear-stops.png)\n\n\u003e **Note**\n\u003e 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.\n\n##### Stops positions\n\nIn addition to setting the opacity of the stops, you can also set the **position** using `mask-point`.\n\n```html\n\u003cdiv class=\"mask-linear mask-point-from-[10%] mask-via-10 mask-point-via-[30%] mask-to-100\" /\u003e\n\u003cdiv class=\"mask-linear mask-dir-to-r mask-to-[0.05] mask-point-to-[50%]\" /\u003e\n```\n![stops' points example](examples/mask-linear-stops-points.png)\n\nThis utility don't accept any default value, so use arbitrary values.\n\n### `radial`\n\nApplies 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.\n\n```html\n\u003cdiv class=\"mask-radial\" /\u003e\n```\n![mask-radial example](examples/mask-radial.png)\n\n#### Shape `mask-shape`\n\n[Shape](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/radial-gradient#values) of the gradient, `ellipse` (by default) or `circle`.\n\n```html\n\u003cdiv class=\"mask-radial mask-shape-ellipse\" /\u003e\n\u003cdiv class=\"mask-radial mask-shape-circle\" /\u003e\n```\n![mask-shape example](examples/mask-shape.png)\n\n#### Position `mask-at`\n\nBy 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.\n\n```html\n\u003cdiv class=\"mask-radial mask-at-[30px_40px]\" /\u003e\n```\n![mask-at example](examples/mask-at.png)\n\n#### Reach `mask-reach`\n\nWith this util you can specify the size of the gradient.\n\n```html\n\u003cdiv class=\"mask-radial mask-reach-closest-side\" /\u003e\n\u003cdiv class=\"mask-radial mask-reach-closest-corner\" /\u003e\n\u003cdiv class=\"mask-radial mask-reach-farthest-side\" /\u003e\n\u003cdiv class=\"mask-radial mask-reach-farthest-corner\" /\u003e\n```\n![mask-reach example](examples/mask-reach.png)\n\nBesides *as-they-are* keyword-values, there are also a couple of aliases:\n- `mask-reach-contain` for `closest-side`\n- `mask-reach-cover` for `farthest-corner`\n\nYou can also use arbitrary values:\n\n```html\n\u003cdiv class=\"mask-reach-[40%_2rem] mask-radial\" /\u003e\n\u003cdiv class=\"mask-reach-[40%_150%] mask-radial\" /\u003e\n```\n![example for mask-reach with arbitrary values](examples/mask-reach-arbitrary.png)\n\n#### Stops\n\n\u003e **Note**\n\u003e The opacity stops for `mask-radial` are the same as [the ones described for `mask-linear`](#opacity-stops), including [points API](#stops-positions).\n\n```html\n\u003cdiv class=\"mask-radial mask-from-0 mask-via-[0.25]\" /\u003e\n\u003cdiv class=\"mask-radial mask-from-0 mask-via-[0.75] mask-to-100\" /\u003e\n\u003cdiv class=\"mask-radial mask-from-0 mask-point-from-[2rem] mask-via-[0.75] mask-point-via-[3rem]\" /\u003e\n```\n![mask-radial stops' example](examples/mask-radial-stops.png)\n\n\n### `none`\n\nThis 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.\n\n```html\n\u003cdiv class=\"mask-linear sm:mask-none\" /\u003e\n```\n![mask-none example](examples/mask-none.png)\n\n\n### Arbitrary values\n\n#### Images\n\nThe `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.\n\n```html\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')]\" /\u003e\n```\n![arbitrary mask image example](examples/arbitrary-image.png)\n\n#### Gradients\n\nYou can pass other types of the gradients, e.g. `conic-gradient` etc.\n\n```html\n\u003cdiv class=\"mask-[conic-gradient(from_45deg,_black,_transparent)]\" /\u003e\n```\n![arbitrary conic-gradient mask example](examples/arbitrary-conic-gradient.png)\n\nAlso, you may want not to use the API above even for `linear-gradient` or `radial-gradient` so you can pass them arbitrarily too.\n\n```html\n\u003cdiv class=\"mask-[linear-gradient(12deg,_black,_transparent)]\" /\u003e\n```\n\n\n## mask-size\n\n```html\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-size-cover\" /\u003e\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-size-contain\" /\u003e\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-size-[4rem]\" /\u003e\n```\n![mask size example](examples/mask-size.png)\n\n\n## mask-position\n\n```html\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-no-repeat  mask-position-left-bottom\" /\u003e\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-no-repeat mask-position-center\" /\u003e\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-no-repeat mask-position-[0.5rem_25%]\" /\u003e\n```\n![mask position example](examples/mask-position.png)\n\n\n## mask-repeat\n\nYou can manage the [`mask-repeat` css property](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-repeat) as well with the following utilities:\n- `mask-repeat`\n- `mask-repeat-x`\n- `mask-repeat-y`\n- `mask-repeat-space`\n- `mask-repeat-round`\n- `mask-no-repeat`\n\n```html\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-repeat\" /\u003e\n\u003cdiv class=\"mask-[url('/your-pretty-image.png')] mask-no-repeat\" /\u003e\n```\n![mask-repeat example](examples/mask-repeat.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyncz%2Ftailwind-mask-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyncz%2Ftailwind-mask-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyncz%2Ftailwind-mask-image/lists"}