attrs-in-props

attrs-in-props

HTML attributes as props for DOMQL elements. Provides attribute validation, filtering, and automatic resolution for HTML elements.

What it does

• Validates HTML attributes by tag name (knows which attributes are valid for <img>, <a>, <input>, etc.)
• Filters props to extract valid HTML attributes and DOM events
• Provides attribute transform plugins for common patterns (src, href resolution)
• Supports all standard HTML attributes, ARIA attributes, SVG attributes, and DOM events

API

checkAttributeByTagName(tag, attribute)

Check if an attribute is valid for a specific HTML tag.

import { checkAttributeByTagName } from 'attrs-in-props'

checkAttributeByTagName('img', 'src')     // true
checkAttributeByTagName('img', 'href')    // false
checkAttributeByTagName('div', 'id')      // true (default attribute)

filterAttributesByTagName(tag, props, cssProps?)

Filter component props to extract only valid HTML attributes and DOM events.

import { filterAttributesByTagName } from 'attrs-in-props'

filterAttributesByTagName('img', {
  src: '/photo.jpg',
  alt: 'Photo',
  theme: 'primary',     // filtered out (not an HTML attr)
  padding: '10px'       // filtered out (CSS prop)
})
// -> { src: '/photo.jpg', alt: 'Photo' }

resolvePropValue(el, value)

Resolves a prop value: executes dynamic values and replaces {{template}} literals.

import { resolvePropValue } from 'attrs-in-props'

// In an attr handler:
const src = resolvePropValue(el, el.src)

ATTR_TRANSFORMS

Auto-resolve map for common attributes. Handles exec + template literal replacement for: src, href, action, poster, data.

import { ATTR_TRANSFORMS, applyAttrTransforms } from 'attrs-in-props'

// Apply all valid transforms for an element's tag
const attrs = applyAttrTransforms(element)

Components using standard src/href patterns no longer need custom attr blocks — ATTR_TRANSFORMS handles resolution automatically.

executeAttr(elem, element)

Execute all handler functions in an element's attr block.

import { executeAttr } from 'attrs-in-props'

const resolved = executeAttr(componentDef, element)
// -> { src: '/resolved-path.jpg', alt: 'Photo' }

ARIA Attributes

All aria-* attributes are valid on any element. Three syntax forms are supported:

// 1. Kebab-case (standard HTML)
{ 'aria-label': 'Close', 'aria-expanded': true }

// 2. camelCase (JS-friendly) — auto-converted to kebab-case
{ ariaLabel: 'Close', ariaExpanded: true }

// 3. Object shorthand
{ aria: { label: 'Close', expanded: true, hidden: false } }

All three produce aria-label="Close", aria-expanded="true" in the DOM.

Data Attributes

All data-* attributes are valid on any element, with the same three syntax forms:

{ 'data-testid': 'btn' }         // kebab-case
{ dataTestId: 'btn' }            // camelCase → data-test-id
{ data: { testId: 'btn' } }     // object shorthand → data-test-id

Conditional Attributes

Attributes inside $, ., ! prefix blocks are conditionally applied — same prefixes as css-in-props:

const Button = {
  // $ prefix: global case from context.cases
  '$isSafari': { disabled: true, 'aria-label': 'Safari' },

  // . prefix: truthy (element/state first, then context.cases)
  '.isActive': { aria: { expanded: true }, 'data-state': 'open' },

  // ! prefix: falsy
  '!isActive': { ariaHidden: true }
}

Conditional attribute values are wrapped in functions and re-evaluated on every update() call.

extractConditionalAttrs(props, tag, cssProps?)

Extract HTML attributes from conditional blocks in props.

import { extractConditionalAttrs } from 'attrs-in-props'

const conditionalAttrs = extractConditionalAttrs(props, 'button', cssPropsRegistry)
// Returns attr functions that evaluate conditions on each call

Default attributes

All HTML elements support these attributes by default: id, title, class, style, dir, lang, hidden, tabindex, draggable, contenteditable, spellcheck, translate, role, slot, and more.

All aria-* and data-* attributes are valid on any element. Element-specific attributes are supported for 50+ HTML tags including a, img, input, video, iframe, form, select, textarea, and svg.