CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-unocss--preset-attributify

Attributify preset for UnoCSS that enables using utility classes as HTML attributes rather than class names.

—

Pending
Overview
Eval results
Files

variant-processing.mddocs/

Variant Processing

Processes attributify selectors with variants like pseudo-classes, responsive breakpoints, and other UnoCSS variants, converting attribute-based variants into standard UnoCSS utility format.

Capabilities

Variant Function

Creates a variant handler for processing attributify selectors with UnoCSS variants.

/**
 * Creates a variant handler for processing attributify selectors
 * @param options - Configuration options for variant processing
 * @returns UnoCSS VariantObject
 */
function variantAttributify(options: AttributifyOptions = {}): VariantObject;

interface VariantObject {
  name: 'attributify';
  match(input: string, context: VariantContext): string | VariantMatch[] | undefined;
}

interface VariantContext {
  generator?: UnoGenerator;
}

interface VariantMatch {
  matcher: string;
}

Usage Examples:

import { variantAttributify } from '@unocss/preset-attributify'

// Create variant handler with default options
const variant = variantAttributify()

// Create variant handler with custom options  
const customVariant = variantAttributify({
  prefix: 'ui-',
  prefixedOnly: true,
  trueToNonValued: true
})

Variants Regex

Regular expression for parsing variant prefixes from attribute values.

/**
 * Regular expression for parsing variants from attribute values
 * Matches variant prefixes like "hover:", "sm:", etc.
 * Pattern: /^(?!.*\[[^:]+:.+\]$)((?:.+:)?!?)(.*)$/
 */
const variantsRE: RegExp;

Variant Processing Logic

The variant handler processes attributify selectors through these steps:

  1. Selector Validation: Checks if input is a valid attributify selector
  2. Prefix Handling: Strips or validates attribute prefixes
  3. Variant Parsing: Extracts variant prefixes from attribute values
  4. Self-Reference Expansion: Handles special ~ syntax for attribute names
  5. Ambiguity Resolution: Handles ambiguous variant/value combinations

Selector Patterns

The variant handler processes these selector patterns:

Basic Attributify Selector:

// Input: [bg~="blue-500"]
// Output: "bg-blue-500"

With Variants:

// Input: [bg~="hover:blue-500"]  
// Output: "hover:bg-blue-500"

Self-Reference:

// Input: [hover~="~"]
// Output: "hover:hover" (attribute name becomes utility)

Non-Valued Attributes:

// Input: [mt-2=""]
// Output: "mt-2"

// With trueToNonValued: true
// Input: [mt-2="true"] 
// Output: "mt-2"

Complex Variants:

// Input: [text~="sm:hover:red-500"]
// Output: "sm:hover:text-red-500"

Ambiguity Resolution

The variant handler resolves ambiguous cases where variants and values could be interpreted multiple ways:

Numeric Values with Variants:

<!-- Ambiguous: border="red:10" -->
<!-- Could be: border-red:10 OR red:border-10 -->
<div border="red:10"></div>

Resolution Strategy:

// Returns both possibilities as VariantMatch[]
[
  { matcher: "red:border-10" },    // Variant interpretation
  { matcher: "border-red:10" }     // Value interpretation  
]

Prefix Handling

The variant handler respects prefix configuration:

With Prefix:

// options.prefix = "ui-"
// Input: [ui-bg~="blue-500"]
// Output: "bg-blue-500"

// options.prefixedOnly = true
// Input: [bg~="blue-500"] (no prefix)
// Output: undefined (ignored)

Self-Reference Syntax

Special handling for the ~ self-reference syntax:

<!-- Attribute name becomes the utility -->
<div hover="~"></div>        <!-- hover:hover -->
<div focus="~"></div>        <!-- focus:focus -->
<div bg="red-500 hover:~"></div>  <!-- bg-red-500 hover:bg -->

Bracket Value Processing

Handles bracket notation for arbitrary values:

// Input: [w~="[200px]"]
// Output: "w-[200px]"

// With variants
// Input: [w~="sm:[200px]"]  
// Output: "sm:w-[200px]"

Complex Variant Examples

Responsive Breakpoints:

<div text="sm:lg md:xl lg:2xl"></div>

Generates:

  • sm:text-lg
  • md:text-xl
  • lg:text-2xl

Pseudo-Classes:

<div bg="blue-500 hover:blue-600 focus:blue-700"></div>

Generates:

  • bg-blue-500
  • hover:bg-blue-600
  • focus:bg-blue-700

Combined Variants:

<div text="sm:hover:red-500 lg:focus:blue-500"></div>

Generates:

  • sm:hover:text-red-500
  • lg:focus:text-blue-500

Dark Mode:

<div bg="white dark:black text="black dark:white"></div>

Generates:

  • bg-white
  • dark:bg-black
  • text-black
  • dark:text-white

Error Handling

The variant handler handles these edge cases:

  • Invalid attributify selectors (returns undefined)
  • Missing or malformed variant syntax
  • Conflicting prefix requirements
  • Invalid bracket notation
  • Circular self-references

Integration with UnoCSS

The variant handler integrates with UnoCSS's variant system:

// Part of preset configuration
{
  variants: [variantAttributify(options)]
}

The handler works alongside other UnoCSS variants and respects the global variant configuration.

Install with Tessl CLI

npx tessl i tessl/npm-unocss--preset-attributify

docs

autocomplete-support.md

html-extraction.md

index.md

preset-configuration.md

typescript-definitions.md

variant-processing.md

tile.json