juncheng.li 27cf5ae2d3 add modules		2 years ago
..
LICENSE	add modules	2 years ago
README.md	add modules	2 years ago
package.json	add modules	2 years ago

README.md

@unocss/preset-attributify

Attributify Mode for UnoCSS.

Installation

npm i -D @unocss/preset-attributify

import presetAttributify from '@unocss/preset-attributify'

Unocss({
  presets: [
    presetAttributify({ /* options */ }),
    // ...other presets
  ],
})

Attributify Mode

This preset enabled Windi CSS's Attributify Mode for other presets.

Imagine you have this button using Tailwind's utilities. When the list gets long, it becomes really hard to read and maintain.

<button class="bg-blue-400 hover:bg-blue-500 text-sm text-white font-mono font-light py-2 px-4 rounded border-2 border-blue-200 dark:bg-blue-500 dark:hover:bg-blue-600">
  Button
</button>

With attributify mode, you can separate utilities into attributes:

<button 
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>

For example, text-sm text-white could be grouped into text="sm white" without duplicating the same prefix.

Prefix Self-referencing

For utilities like flex, grid, border, that have the utilities same as the prefix, a special ~ value is provided.

For example:

<button class="border border-red">
  Button
</button>

Can be written as

<button border="~ red">
  Button
</button>

Valueless Attributify

In addition to Windi CSS's Attributify Mode, this presets also supports valueless attributes.

For example,

<div class="m-2 rounded text-teal-400" />

now can be

<div m-2 rounded text-teal-400 />

Note: If you are using JSX, <div foo> might be transformed to <div foo={true}> which will make the generate CSS from UnoCSS failed to match the attributes. To solve this, you might want to try transformer-attributify-jsx along with this preset.

Properties Conflicts

If the name of the attributes mode ever conflicts with the elements' or components' properties, you can add un- prefix to be specific to UnoCSS's attributify mode.

For example:

<a text="red">This conflicts with links' `text` prop</a>
<!-- to -->
<a un-text="red">Text color to red</a>

Prefix is optional by default, if you want to enforce the usage of prefix, set

presetAttributify({
  prefix: 'un-',
  prefixedOnly: true, // <--
})

You can also disable the scanning for certain attributes by:

presetAttributify({
  ignoreAttributes: [
    'text'
    // ...
  ]
})

TypeScript Support (JSX/TSX)

Create shims.d.ts with the following content:

By default, the type includes common attributes from @unocss/preset-uno. If you need custom attributes, refer to the type source to implement your own type.

Vue

Since Volar 0.36, it's now strict to unknown attributes. To opt-out, you can add the following file to your project:

// html.d.ts
declare module '@vue/runtime-dom' {
  interface HTMLAttributes {
    [key: string]: any
  }
}
declare module '@vue/runtime-core' {
  interface AllowedComponentProps {
    [key: string]: any
  }
}
export {}

React

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'react' {
  interface HTMLAttributes<T> extends AttributifyAttributes {}
}

Vue 3

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module '@vue/runtime-dom' {
  interface HTMLAttributes extends AttributifyAttributes {}
}

SolidJS

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'solid-js' {
  namespace JSX {
    interface HTMLAttributes<T> extends AttributifyAttributes {}
  }
}

Svelte & SvelteKit

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare global {
  namespace svelte.JSX {
    interface HTMLAttributes<T> extends AttributifyAttributes {}
  }
}

Astro

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare global {
  namespace astroHTML.JSX {
    interface HTMLAttributes extends AttributifyAttributes { }
  }
}

Preact

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'preact' {
  namespace JSX {
    interface HTMLAttributes extends AttributifyAttributes {}
  }
}

Attributify with Prefix

import type { AttributifyNames } from '@unocss/preset-attributify'

type Prefix = 'uno:' // change it to your prefix

interface HTMLAttributes extends Partial<Record<AttributifyNames<Prefix>, string>> {}

Credits

Initial idea by @Tahul and @antfu. Prior implementation in Windi CSS by @voorjaar.