{"id":13480136,"url":"https://github.com/babichjacob/tailwindcss-custom-native","last_synced_at":"2025-03-16T12:31:49.406Z","repository":{"id":65514210,"uuid":"186973632","full_name":"babichjacob/tailwindcss-custom-native","owner":"babichjacob","description":"Tailwind CSS plugin that lets you write your configuration file with your own custom utilities as though they were native to the framework","archived":false,"fork":false,"pushed_at":"2023-10-04T02:41:46.000Z","size":403,"stargazers_count":65,"open_issues_count":8,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-08-16T06:01:18.318Z","etag":null,"topics":["tailwindcss","tailwindcss-plugin"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/babichjacob.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":"2019-05-16T07:18:52.000Z","updated_at":"2023-08-25T17:28:09.000Z","dependencies_parsed_at":"2024-07-22T17:54:44.045Z","dependency_job_id":null,"html_url":"https://github.com/babichjacob/tailwindcss-custom-native","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"0bfcfd637bf0a5b2e2f6aadbe984c413003f67cc"},"previous_names":["sirnavith/tailwindcss-custom-native"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babichjacob%2Ftailwindcss-custom-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babichjacob%2Ftailwindcss-custom-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babichjacob%2Ftailwindcss-custom-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babichjacob%2Ftailwindcss-custom-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/babichjacob","download_url":"https://codeload.github.com/babichjacob/tailwindcss-custom-native/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243814880,"owners_count":20352037,"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":["tailwindcss","tailwindcss-plugin"],"created_at":"2024-07-31T17:00:35.028Z","updated_at":"2025-03-16T12:31:49.108Z","avatar_url":"https://github.com/babichjacob.png","language":"TypeScript","readme":"# 🧩 Tailwind CSS Custom Native Utilities\nThis Tailwind CSS plugin allows you to write configuration for your own custom utility in the `theme` and `variants` section of your config as though it were actually part of the framework. Just define it with a single line in the `plugins` section!\n\nThis should allow you to finally kill off leftover CSS and inline styles that have no accompanying plugin-made or native utility. Although you can replace other [plugins](https://github.com/aniftyco/awesome-tailwindcss#plugins) with this one, it's probably a good idea to use those instead because they're purpose-built and likely to create a better output.\n\n# 💻 Installation\n\n```bash\nnpm install --save-dev tailwindcss-custom-native\n```\n\n# 🛠 Basic usage\n\nWith this Tailwind configuration,\n\n```js\nmodule.exports = {\n  theme: {\n    // This utility is not native to Tailwind,\n    mixBlendMode: {\n      'screen': 'screen',\n      'overlay': 'overlay',\n    },\n    // So we define it here!\n    customUtilities: {\n      mixBlendMode: {},\n      // There are extra parameters for further customization -- see the advanced usage section\n    },\n  },\n\n  plugins: [\n    require('tailwindcss-custom-native'),\n  ],\n};\n```\n\nthis CSS is generated:\n\n```css\n.mix-blend-mode-screen {\n  mix-blend-mode: screen;\n}\n\n.mix-blend-mode-overlay {\n  mix-blend-mode: overlay;\n}\n```\n\n### Variants\n\nWhen no variants are specified in the `variants` key of your config, no variants will be generated, as you saw above. (If you would prefer for `['responsive']` to be the default, I am open to changing it).\n\nIf you want variants (in the same config as above):\n\n```js\nmodule.exports = {\n  theme: {\n    mixBlendMode: {\n      'screen': 'screen',\n      'overlay': 'overlay',\n    },\n    customUtilities: {\n      mixBlendMode: {},\n    },\n  },\n\n  variants: {\n    // All variants, whether added by plugin or not, are at your disposal\n    mixBlendMode: ['hover', 'focus'],\n  },\n\n  plugins: [\n    require('tailwindcss-custom-native'),\n  ],\n};\n```\n\nyou get this additional CSS:\n\n```css\n.hover\\:mix-blend-mode-screen:hover {\n  mix-blend-mode: screen;\n}\n.hover\\:mix-blend-mode-overlay:hover {\n  mix-blend-mode: overlay;\n}\n\n.focus\\:mix-blend-mode-screen:focus {\n  mix-blend-mode: screen;\n}\n.focus\\:mix-blend-mode-overlay:focus {\n  mix-blend-mode: overlay;\n}\n```\n\n# ⚙️ Full configuration\n\nThis plugin expects configuration of the form\n\n```js\ntheme: {\n  customUtilities: {\n    key: { property, rename, addUtilitiesOptions },\n    // Keep repeating this pattern for more utilities\n  },\n}\n```\n\nWhere each parameter means:\n\n- `key` (required, string) - The name of the key for your custom utility, as you wrote in the `theme` and `variants` section\n\n- `property` (optional, string) - The CSS property that your utility is for\n\n  When not specified, it defaults to kebab-casing (AKA hyphenating) the `key`. For example, `key: 'animationTimingFunction'` has corresponding `property: 'animation-timing-function'`).\n\n  This parameter allows you to use a `key` that may be shorter than the property name, or completely different from it.\n\n- `rename` (optional, string) - The prefix before each value name (from `theme[key]`) in the generated classes\n\n  When not specified, it defaults to kebab-casing (AKA hyphenating) the `key`. For example, `key: 'mixBlendMode'` has corresponding `rename: 'mix-blend-mode'`).\n\n  If set to the empty string (`''`), then there is no prefix and each generated class is just the value name.\n\n- `addUtilitiesOptions` (optional, object) - Extra options to pass to the [`addUtilities`](https://tailwindcss.com/docs/plugins/#adding-utilities) function call.\n\n  As of Tailwind 1.2.0, this just means the [`respectPrefix` and `respectImportant`](https://tailwindcss.com/docs/plugins/#prefix-and-important-preferences) options\n\n# 📚 Examples\n\nSpecify `rename: ''` so you can write `blur-4` and `grayscale` instead of `filter-blur-4` and `filter-grayscale`:\n\n```js\nmodule.exports = {\n  theme: {\n    extend: {\n      customUtilities: {\n        filter: { rename: \"\" },\n      },\n\n      filter: {\n        \"grayscale\": \"grayscale(100%)\",\n        \"blur-4\": \"blur(1rem)\",\n      },\n    },\n  },\n  variants: {\n    filter: [\"responsive\"],\n  },\n  plugins: [\n    require(\"tailwindcss-custom-native\"),\n  ],\n};\n```\n\n```css\n.grayscale {\n  filter: grayscale(100%);\n}\n\n.blur-4 {\n  filter: blur(1rem);\n}\n\n/* Or whatever screen `sm` is in your config */\n@media (min-width: 640px) {\n  .sm\\:grayscale {\n    filter: grayscale(100%);\n  }\n\n  .sm\\:blur-4 {\n    filter: blur(1rem);\n  }\n}\n\n/* ... and so on for the other screens */\n```\n\nAny property named with a `-` in front will have that moved to the front of the generated class name, just like the native [`margin`](https://tailwindcss.com/docs/margin/#negative-values) or [`z-index`](https://tailwindcss.com/docs/z-index/#negative-values) utilities do.\n\nLet's say you want a section specifically for blur utilities, because they *really* have nothing to do with other kinds of CSS filters. Use `'blur'` as the `key` and `'filter'` as the `property`:\n\n```js\nmodule.exports = {\n  theme: {\n    extend: {\n      blur: {\n        '0': 'blur(0)',\n        '1': 'blur(0.25rem)',\n        '2': 'blur(0.5rem)',\n        // ... as many numbers as you want\n      },\n\n      customUtilities: {\n        blur: { property: 'filter' },\n      },\n    },\n  },\n  variants: {\n    blur: ['active'],\n  },\n  plugins: [\n    require('tailwindcss-custom-native'),\n  ],\n};\n```\n\n```css\n.blur-0 {\n  filter: blur(0);\n}\n\n.blur-1 {\n  filter: blur(0.25rem);\n}\n\n.blur-2 {\n  filter: blur(0.5rem);\n}\n\n.active\\:blur-0:active {\n  filter: blur(0);\n}\n\n.active\\:blur-1:active {\n  filter: blur(0.25rem);\n}\n\n.active\\:blur-2:active {\n  filter: blur(0.5rem);\n}\n\n/* and so on for the other numbers you specified */\n```\n\nIn practice, you will probably need more than one custom utility, so just add another to the list:\n\n```js\nmodule.exports = {\n  theme: {\n    customUtilities: {\n      listStyleImage: { rename: \"list\" },\n      scrollBehavior: { rename: \"scroll\" },\n    },\n\n    listStyleImage: {\n      checkmark: \"url('/img/checkmark.png')\",\n    },\n\n    scrollBehavior: {\n      immediately: \"auto\",\n      smoothly: \"smooth\",\n    },\n  },\n  variants: {},\n  plugins: [\n    require(\"tailwindcss-custom-native\"),\n  ],\n};\n```\n\n```css\n.list-checkmark {\n  list-style-image: url('/img/checkmark.png');\n}\n\n.scroll-immediately {\n  scroll-behavior: auto;\n}\n\n.scroll-smoothly {\n  scroll-behavior: smooth;\n}\n```\n\nThis plugin can piggyback off of other plugins, especially those that register new variants or are missing relevant utilities. \n\nIn this case, it is used to add some `content` utilities that have `before` and `after` pseudoselector variants, as provided by `tailwindcss-pseudo`:\n\n```js\nmodule.exports = {\n  theme: {\n    extend: {\n      content: {\n        empty: \"''\",\n        smile: \"'\\\\1F60A'\",\n        checkmark: \"url(/img/checkmark.png)\",\n      },\n\n      customUtilities: {\n        content: {},\n      },\n\n      // This is tailwindcss-pseudo config\n      pseudo: {\n        before: \"before\",\n        after: \"after\",\n      },\n    },\n  },\n  variants: {\n    content: [\"before\", \"after\"],\n  },\n  plugins: [\n    require(\"tailwindcss-pseudo\")(),\n    require(\"tailwindcss-custom-native\"),\n  ],\n};\n```\n\n```css\n.content-empty {\n  content: \"\";\n}\n.content-smile {\n  content: \"\\1F60A\";\n}\n.content-checkmark {\n  content: url(/img/checkmark.png);\n}\n\n.before\\:content-empty::before {\n  content: \"\";\n}\n.before\\:content-smile::before {\n  content: \"\\1F60A\";\n}\n.before\\:content-checkmark::before {\n  content: url(/img/checkmark.png);\n}\n\n.after\\:content-empty::after {\n  content: \"\";\n}\n.after\\:content-smile::after {\n  content: \"\\1F60A\";\n}\n.after\\:content-checkmark::after {\n  content: url(/img/checkmark.png);\n}\n```\n\n## 😵 Help! I have a question\n\n[Create an issue](https://github.com/babichjacob/tailwindcss-custom-native/issues/new) and I'll try to help.\n\n## 😡 Fix! There is something that needs improvement\n\n[Create an issue](https://github.com/babichjacob/tailwindcss-custom-native/issues/new) or [pull request](https://github.com/babichjacob/tailwindcss-custom-native/pulls) and I'll try to fix.\n\n## 📄 License\n\nMIT\n\n---\n\n*Repository preview image generated with [GitHub Social Preview](https://social-preview.pqt.dev/)*\n","funding_links":[],"categories":["Plugins"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabichjacob%2Ftailwindcss-custom-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbabichjacob%2Ftailwindcss-custom-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabichjacob%2Ftailwindcss-custom-native/lists"}