Skip to content

Commit fcec149

Browse files
committed
docs (#82): update base example for attrs fallthrough
1 parent 428d2d1 commit fcec149

File tree

1 file changed

+33
-29
lines changed

1 file changed

+33
-29
lines changed

src/guide/component-props.md

Lines changed: 33 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -259,24 +259,52 @@ app.component('date-picker', {
259259
In the event we need to define the status of the date-picker component via a `data-status` property, it will be applied to the root node (i.e., `div.date-picker`).
260260

261261
```html
262+
<!-- Date-picker component with a non-prop attribute -->
262263
<date-picker data-status="activated"></date-picker>
263-
```
264264

265-
```html
266-
<!-- Rendered DatePicker Component -->
265+
<!-- Rendered date-picker component -->
267266
<div class="date-picker" data-status="activated">
268267
<input type="datetime" />
269268
</div>
270269
```
271270

272271
### Disabling Attribute Inheritance
273272

273+
If you do **not** want the a component to automatically inherit attributes, you can set `inheritAttrs: false` in the component's options.
274+
274275
There are two common scenarios when attribute inheritance needs to be disabled:
275276

276277
1. When attributes need to be applied to other elements besides the root node
277278
1. When a component has multiple root nodes (i.e., a [fragment](TODO:fragment.md))
278279

279-
To disable automatic attribute inheritance, you can set `inheritAttrs: false` in the component's options. For example:
280+
By defining the `inheritAttrs` option on your component, this gives you access to the component's `$attrs` property, which includes all non-prop attributes (e.g., `class`, `style`, `v-on` listeners, etc.).
281+
282+
Using our date-picker component example from the [previous section]('#attribute-inheritance), in the event we need to apply all non-prop attributes to the `input` element rather than the root `div` element, this can be accomplished by using the `v-bind` shortcut.
283+
284+
```js{5}
285+
app.component('date-picker', {
286+
inheritAttrs: false,
287+
template: `
288+
<div class="date-picker">
289+
<input type="datetime" v-bind="$attrs" />
290+
</div>
291+
`
292+
})
293+
```
294+
295+
With this new configuration, our `data-status` attribute will be applied to our `input` element!
296+
297+
```html
298+
<!-- Date-picker component with a non-prop attribute -->
299+
<date-picker data-status="activated"></date-picker>
300+
301+
<!-- Rendered date-picker component -->
302+
<div class="date-picker">
303+
<input type="datetime" data-status="activated" />
304+
</div>
305+
```
306+
307+
For example:
280308

281309
```js
282310
const app = Vue.createApp({})
@@ -287,7 +315,7 @@ app.component('my-component', {
287315
})
288316
```
289317

290-
When you disable `inheritAttrs`, this gives you to access the `$attrs` property, which includes all non-prop attributes (e.g., `class`, `style`, `v-on` listeners, etc.). With `inheritAttrs: false` and `$attrs`, you can explicitly determine which element you want to forward attributes to, which is often desirable for [base components](../style-guide/#base-component-names-strongly-recommended):
318+
With `inheritAttrs: false` and `$attrs`, you can manually decide which element you want to forward attributes to, which is often desirable for [base components](../style-guide/#base-component-names-strongly-recommended):
291319

292320
```js
293321
app.component('base-input', {
@@ -318,30 +346,6 @@ This pattern allows you to use base components more like raw HTML elements, with
318346

319347
If you did not apply `this.$attrs` in a multi-root component explicitly, a runtime warning will be emitted. You can suppress this warning with [Disabling Attribute Inheritance](#disabling-attribute-inheritance).
320348

321-
### Replacing/Merging with Existing Attributes
322-
323-
Imagine this is the template for `bootstrap-date-input`:
324-
325-
```html
326-
<input type="date" class="form-control" />
327-
```
328-
329-
To specify a theme for our date picker plugin, we might need to add a specific class, like this:
330-
331-
```html
332-
<bootstrap-date-input
333-
data-date-picker="activated"
334-
class="date-picker-theme-dark"
335-
></bootstrap-date-input>
336-
```
337-
338-
In this case, two different values for `class` are defined:
339-
340-
- `form-control`, which is set by the component in its template
341-
- `date-picker-theme-dark`, which is passed to the component by its parent
342-
343-
For most attributes, the value provided to the component will replace the value set by the component. So for example, passing `type="text"` will replace `type="date"` and probably break it! Fortunately, the `class` and `style` attributes are a little smarter, so both values are merged, making the final value: `form-control date-picker-theme-dark`.
344-
345349
## Prop Casing (camelCase vs kebab-case)
346350

347351
HTML attribute names are case-insensitive, so browsers will interpret any uppercase characters as lowercase. That means when you're using in-DOM templates, camelCased prop names need to use their kebab-cased (hyphen-delimited) equivalents:

0 commit comments

Comments
 (0)