Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 87 ยท Components

Fallthrough Attributes

Learn how Vue passes class, style, ids and event listeners from a parent to a component's root element, and how inheritAttrs false and $attrs give you full control.

Imagine you wrote a BaseButton component. A teammate uses it as <BaseButton class="danger" id="delete" @click="remove">Delete</BaseButton>. You never declared class, id or a click handler in your component, yet all three work. That is attribute fallthrough: attributes and event listeners that a component does not claim as props or emits are automatically applied to the component's root element.

Fallthrough is what lets small wrapper components feel like real HTML elements. It also has sharp edges: the root element is not always the element you want to receive the attributes (think of an input wrapped in a label), and components with several root nodes do not know where to put them. This lesson shows the default rules, how class and style merge, how to switch the behaviour off with inheritAttrs: false, and how to place $attrs yourself. It follows Slots and uses the same template-string style of components.

The examples load the full browser build of Vue 3.5.13 (the one that can compile template strings) from jsDelivr. In a project with a build tool you would write the same components as .vue files, which are shown here as read-only blocks.

The default: attributes fall through to the root

Any attribute that is not declared as a prop or emit, plus class, style and v-on listeners, lands on the root element of the child.

flowchart LR
  P["Parent writes<br/>&lt;BaseButton class='danger' id='delete' @click='remove'&gt;"] --> C["BaseButton"]
  C -->|"props and emits are removed"| F["Fallthrough set:<br/>class, id, onClick"]
  F --> R["Root element<br/>&lt;button class='btn'&gt;"]

Declared props and emits are consumed by the component; everything else is applied to the root element.

The next example prints the real HTML of the rendered buttons so you can see exactly what Vue produced. Look at the class list: the component's own btn class and the parent's danger class are merged, not replaced. style is merged in the same way. For any other attribute, the parent's value wins over a value the root element sets itself. A click listener passed from the parent runs in addition to a listener on the root.

Class and style merge on the root element

Press the Delete button: the listener the parent attached to the component fires, even though BaseButton never mentions clicks. Because a listener is just an attribute named onClick as far as the component can tell, a native listener on the child's root would not be replaced either: both run.

Why you sometimes want to turn it off

The default breaks down when the root element is only a wrapper. Consider a labelled text field:

HTML
<!-- LabeledInput.vue (read-only) -->
<template>
  <label class="field">
    <span>{{ label }}</span>
    <input type="text" />
  </label>
</template>

A parent writes <LabeledInput label="Name" placeholder="Ada" maxlength="5" />. Vue puts placeholder and maxlength on the <label>, where they do nothing. What you want is for them to reach the <input>. Two tools solve this:

  1. inheritAttrs: false tells Vue not to apply the fallthrough set to the root automatically.
  2. $attrs is an object holding that fallthrough set (class, style, ids, and listeners such as onClick). Spread it with v-bind="$attrs" wherever you like.
flowchart TB
  A["Fallthrough set<br/>($attrs)"] --> B{"inheritAttrs"}
  B -->|"true (default)"| C["Applied to the root element"]
  B -->|"false"| D["Applied only where you write v-bind='$attrs'"]

With inheritAttrs: false you decide which element receives the attributes.

In <script setup> you declare the option in a separate plain <script> block, or with defineOptions({ inheritAttrs: false }). Inside <script setup> you read the attributes with useAttrs(). In the Options API you write inheritAttrs: false next to props.

The live example has two versions of the field. The first forwards everything to the input, including the class. The second keeps the class and style on the outer wrapper (where layout belongs) and forwards only the remaining attributes to the input. It does that with a small helper that removes class and style from $attrs.

Forwarding $attrs to an inner element

Notice that in the first field the wide class ends up on the <input> (which is why it is wide), while in the second field the boxed class sits on the <label> and only placeholder and maxlength reach the input.

Facts about $attrs worth knowing

  • $attrs contains listeners as onClick-style keys, so one v-bind="$attrs" forwards both attributes and events.
  • It does not contain declared props or declared emits. Once you declare label as a prop, it leaves $attrs.
  • Attribute names keep their original form: data-id stays data-id, but an event listener @my-event appears as onMyEvent.
  • $attrs is always current when you read it during render, but it is not reactive for watchers. If you need to react to a change, make it a prop, or use onUpdated.
  • Boolean-like attributes without a value are passed as an empty string (<Comp disabled> gives disabled: ""), which is still truthy in the DOM sense and disables a native input.

Components with several root nodes

A component whose template has more than one top-level node (a fragment) has no single root, so Vue cannot know where to put the fallthrough attributes. In development Vue prints a warning ("Extraneous non-props attributes") if the parent passes any. The fix is the same tool: bind $attrs explicitly on the element that should receive them.

Choosing the target in a multi-root component

The heading stays untouched, and the paragraph receives class="hint big" and data-section="shipping".

Accessing attributes in code

In <script setup> the useAttrs() function returns the same object as $attrs, and in setup() it is the attrs property of the second argument. Treat it as read-only, and do not destructure it for later use, because the object is not a reactive source and always reflects the latest values only when read again.

HTML
<!-- Read-only SFC -->
<script setup>
import { useAttrs } from 'vue'

defineOptions({ inheritAttrs: false })
const attrs = useAttrs()
</script>

<template>
  <div class="wrapper">
    <input v-bind="attrs" />
  </div>
</template>

Practical guidance

  • Let fallthrough work for simple wrappers where the root element is the thing users expect (a button, a link, a card).
  • Turn it off when the root is only a layout shell around a form control, and forward $attrs to the real control.
  • Prefer explicit props for anything the component itself needs to understand (a variant, a size). Use $attrs only for "pass-through" HTML attributes.
  • Do not rely on attribute fallthrough to carry data into a component's logic; declare a prop instead, which also documents the component's API. Designing Components discusses this boundary.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A parent writes <BaseButton class="danger"> and BaseButton's root is <button class="btn">. What class does the rendered button have?

    Vue merges class and style from the parent with those on the root element. Other attributes are overridden by the parent's value.
  2. 2. What does inheritAttrs: false do?

    The attributes are still available in $attrs. The option only turns off the automatic application to the root element.
  3. 3. Which values are NOT in $attrs?

    Anything declared via props or emits is consumed by the component and removed from the fallthrough set. Listeners, class, style and other attributes are included.
  4. 4. A component has two root elements and the parent passes class="x". What must the component do to avoid a warning?

    A fragment has no single root for automatic fallthrough. Binding v-bind="$attrs" on one element picks the target explicitly (wrapping in a div also works, but changes the markup).

Summary

  • Attributes and listeners that are not props or emits fall through to the component's root element.
  • class and style are merged with the root's own; listeners both run; other attributes take the parent's value.
  • inheritAttrs: false (or defineOptions) disables automatic application, and v-bind="$attrs" applies the set where you choose.
  • $attrs holds listeners as onXxx keys, excludes declared props and emits, and is not reactive for watchers.
  • Multi-root components must bind $attrs explicitly if the parent passes attributes.
  • Use props for anything the component's logic needs, and fallthrough for plain HTML pass-through.

Continue with sharing data across many levels of components in Provide and Inject.