stack/packages/mosaic/framework/skills/vue-best-practices/reference/attrs-hyphenated-property-access.md

Accessing Hyphenated Attributes in $attrs

Rule

Fallthrough attributes preserve their original casing in JavaScript. Hyphenated attribute names (like data-testid or aria-label) must be accessed using bracket notation. Event listeners are exposed as camelCase functions (e.g., @click becomes $attrs.onClick).

Why This Matters

• JavaScript identifiers cannot contain hyphens
• Using dot notation with hyphenated names causes syntax errors or undefined values
• Event listener naming follows a different convention than attribute naming
• Common source of "undefined" errors when working with attrs programmatically

Bad Code

<script setup>
import { useAttrs } from 'vue';

const attrs = useAttrs();

// WRONG: Syntax error - hyphen interpreted as minus
console.log(attrs.data - testid); // Error!

// WRONG: This accesses a different property
console.log(attrs.dataTestid); // undefined (camelCase doesn't work for attrs)

// WRONG: Expecting hyphenated event name
console.log(attrs['on-click']); // undefined
console.log(attrs['@click']); // undefined
</script>

Good Code

<script setup>
import { useAttrs } from 'vue';

const attrs = useAttrs();

// CORRECT: Use bracket notation for hyphenated attributes
console.log(attrs['data-testid']); // "my-button"
console.log(attrs['aria-label']); // "Submit form"
console.log(attrs['foo-bar']); // "baz"

// CORRECT: Event listeners use camelCase with 'on' prefix
console.log(attrs.onClick); // function
console.log(attrs.onCustomEvent); // function (from @custom-event)
console.log(attrs.onMouseEnter); // function (from @mouseenter or @mouse-enter)
</script>

Attribute vs Event Naming Reference

Parent Usage	$attrs Access
class="foo"	attrs.class
data-id="123"	attrs['data-id']
aria-label="..."	attrs['aria-label']
foo-bar="baz"	attrs['foo-bar']
@click="fn"	attrs.onClick
@custom-event="fn"	attrs.onCustomEvent
@update:modelValue="fn"	attrs['onUpdate:modelValue']

Common Patterns

Checking for specific attributes

<script setup>
import { useAttrs, computed } from 'vue';

const attrs = useAttrs();

// Check if data attribute exists
const hasTestId = computed(() => 'data-testid' in attrs);

// Get aria attribute with default
const ariaLabel = computed(() => attrs['aria-label'] ?? 'Default label');
</script>

Filtering attributes by type

<script setup>
import { useAttrs, computed } from 'vue';

const attrs = useAttrs();

// Separate event listeners from other attributes
const { listeners, otherAttrs } = computed(() => {
  const listeners = {};
  const otherAttrs = {};

  for (const [key, value] of Object.entries(attrs)) {
    if (key.startsWith('on') && typeof value === 'function') {
      listeners[key] = value;
    } else {
      otherAttrs[key] = value;
    }
  }

  return { listeners, otherAttrs };
}).value;
</script>

Extracting data attributes

<script setup>
import { useAttrs, computed } from 'vue';

const attrs = useAttrs();

// Get all data-* attributes
const dataAttrs = computed(() => {
  const result = {};
  for (const [key, value] of Object.entries(attrs)) {
    if (key.startsWith('data-')) {
      result[key] = value;
    }
  }
  return result;
});
</script>

<template>
  <div v-bind="dataAttrs">
    <!-- Only data attributes are bound -->
  </div>
</template>

Forwarding specific events

<script setup>
import { useAttrs } from 'vue';

defineOptions({
  inheritAttrs: false,
});

const attrs = useAttrs();

// Call parent's click handler with custom logic
function handleClick(event) {
  console.log('Internal handling first');

  // Then forward to parent if handler exists
  if (attrs.onClick) {
    attrs.onClick(event);
  }
}
</script>

<template>
  <button @click="handleClick">
    <slot />
  </button>
</template>

TypeScript Considerations

<script setup lang="ts">
import { useAttrs } from 'vue';

const attrs = useAttrs();

// attrs is typed as Record<string, unknown>
// You may need to cast for specific usage

const testId = attrs['data-testid'] as string | undefined;
const onClick = attrs.onClick as ((e: MouseEvent) => void) | undefined;
</script>

References

• Fallthrough Attributes - Accessing in JavaScript
• Vue 3 $attrs Documentation