New directive: v-skip

[Justineo]

Summary

This RFC proposes the addition of a new directive, v-skip. The v-skip directive conditionally skips rendering the current element or component while preserving and promoting its child nodes to the parent level in the node hierarchy. This behavior differs from v-if, which entirely removes the node and its subtree when the condition is false.

Basic example

<template>
  <Tooltip v-skip="!disabled" content="The button is disabled because ...">
    <button :disabled="disabled">Submit</button>
  </Tooltip>
</template>

Motivation

There are scenarios where developers need to conditionally remove an element or component without discarding its children. Currently, achieving this requires workarounds such as using userland components or switching to render functions, which can be verbose and less intuitive.

Related:

• Allow for <component> to be a conditional wrapper ie. only render children. vue#12033

  This issue discussed the need of a conditional wrapper. The workaround (bare basic, not robust) provided in one comments is:

  <template>
    <component :is="tag" v-if="wrap">
      <slot />
    </component>
    <slot v-else />
  </template>
  
  <script setup lang="ts">
  interface Props {
    tag: string;
    wrap: boolean;
  }
  
  defineProps<Props>();
  </script>

  There was also a comment proposing a v-wrap-if directive:

  <div v-wrap-if="someCondition">
    <span>
      This is a span that is sometimes wrapped up in a div.
    </span>
  </div>

• Fragment component #449

  This RFC propsed a built-in fragment component to make utilizing conditional wrappers easier.

  <template>
    <component :is="shouldWrap ? WrapperComponent : 'fragment'">
      <img src="cat.jpg" alt="Cat" />
    </component>
  </template>

• https://dev.to/alexander-nenashev/creating-a-conditional-wrap-component-in-vue-3-18ml

  This post series introduced a way to implement a conditional wrapper component which is quite cumbersome and relied on some knowledge of Vue's internals. The usage of the component is also not as concise as a directive.

The userland component is quite hard to be implemented correctly and when it comes to toggling a component and passing through its props, slots and event listeners, it becomes verbose to use as well. It becomes even harder if we want correct type support.

The v-skip directive aims to provide a more concise and declarative approach to tackle this problem. It eliminates the need for userland components, eases the pain of passing props
or switching to render functions, and makes the code more readable and maintainable.

Detailed design

The v-skip directive accepts an expression that evaluates to a boolean value.

For elements

<div v-skip="condition">
  <p>Hello</p>
</div>

• If condition is truthy, the current node is skipped, and its children are rendered in its place (render as if it's a fragment node) and produces:

  <p>Hello</p>

• Otherwise, the node and its children are rendered normally and produces:

  <div>
    <p>Hello</p>
  </div>

For components

Let's say we have a Tooltip component which is used like this:

<Tooltip>
  <button :disabled="disabled">Submit</button>
  <template #content>
    <em>The button is disabled because ...</em>
  </template>
</Tooltip>

Which renders:

<div>
  <button>Submit</button>
  <div class="tooltip">
    <em>The button is disabled because ...</em>
  </div>
</div>

We can conditionally skip the Tooltip component like this:

<Tooltip v-skip="!disabled">
  <button :disabled="disabled">Submit</button>
  <template #content>
    <em>The button is disabled because ...</em>
  </template>
</Tooltip>

• If disabled is falsy (v-skip evaluates to true), the Tooltip component is skipped, we directly render its default slot in its place and discard other slots, which produces:

<button>Submit</button>

Implementation details

• The children of the node with v-skip directive should be rerendered when the condition changes as the their parent may have provided contextual data (provide, etc.).
• v-skip cannot be used on <template> and <slot>.

Drawbacks

• We may increase the Vue bundle size slightly due to the addition of the new directive.

Alternatives

Alternatives in userland is already covered in the motivation section.

Regarding to the naming, we can also consider alternatives like:

• v-skip-if
• v-wrap
• v-wrap-if
• v-unwrap
• v-unwrap-if

Adoption strategy

Backward Compatibility

The addition of v-skip does not break existing code and is entirely opt-in.

Documentation

Comprehensive documentation and examples will be provided to educate developers on proper usage.

Tooling Support

We need built-in support from Vue Devtools and the official language support to recognize and correctly parse the v-skip directive. We also need to add linting rules to eslint-plugin-vue enforce proper usage of the directive.

Unresolved questions

N/A

---

Additional suggestions from comments

• v-contents

[UncleBill]

I like this. It looks similar to display: contents, so I would like to suggest another alternative name v-contents.

https://developer.mozilla.org/zh-CN/docs/Web/CSS/display#display_contents

[Deer404]

Useful directive reduce boilerplate code. The name v-wrap feels more appropriate.

[warmthsea]

I like it very much.

[chriscalo]

I agree this feels like a nice way to clean up what is otherwise a bit convoluted to get right in userland.

I'd suggest that the name v-unwrap feels closest to what this does. Here's why:

If you consider the template with and without this, if you don't use this directive, you get the parent element and its children rendered:

<!-- rendered HTML without directive -->
<div>
  <p>Hello</p>
</div>

And when you do use this directive, you get only the children rendered.

<!-- rendered HTML with this directive "activated" -->
<p>Hello</p>

For this reason, the real function this directive performs is "unwrapping" the children by removing the parent. Hence why I think v-unwrap is the most natural name for readers of code that uses this to understand what it does.

v-wrap implies you might get ANOTHER wrapping element.

v-skip sounds like an inversion of what v-if does.

[sugoidesune]

I think negatives should not be used as it increases cognitive load.

v-if = true
v-show = true
// display the element when true.

v-wrap = true
// displays the wrapping element when true.

having a true value remove an element is unintuitive, even if the naming is straight forward.
So whatever the final naming - a true value should display it, and a false value should not.

[adamdehaven]

• I don’t prefer naming v-skip since it doesn’t indicate the children will still be rendered.
  • v-wrap - indicate you want to wrap the children. I think this makes sense so that true indicates “wrapping children” and false indicates not wrapping
• Would it also allow for nested elements with the same directive?
• Could utilizing the directive lead to hydration errors in SSR? (I think no, but asking)

[Justineo]

• Would it also allow for nested elements with the same directive?

Probably no reason to not allow that? Do you think of any issue if this is allowed?

• Could utilizing the directive lead to hydration errors in SSR? (I think no, but asking)

I think no. It should be basically a syntax sugar for existing features.

<Tooltip v-skip="!disabled">
  <button :disabled="disabled">Submit</button>
  <template #content>
    <em>The button is disabled because ...</em>
  </template>
</Tooltip>

This should be equivalent to

<Tooltip v-if="disabled">
  <button :disabled="disabled">Submit</button>
  <template #content>
    <em>The button is disabled because ...</em>
  </template>
</Tooltip>
<button v-else :disabled="disabled">Submit</button>

[spaceemotion]

I also think v-skip is not the right name. Today, I added a similar functionality using the following component:

// TemplatePassthrough.ts

import type { FunctionalComponent } from "vue";

const TemplatePassthrough: FunctionalComponent = (_, ctx) => (ctx.slots.default?.() ?? null);

export default TemplatePassthrough;

that I then was able to use as follows:

<script setup lang="ts">
  defineProps<{
    type: 'menu' | 'submenu' | 'inline';
  }>();
</script>

<template>
  <component
    :is="
      type === 'menu'
        ? UiMenu
        : type === 'submenu'
          ? UiSubMenu
          : TemplatePassthrough
    "
  >
    <!-- actual contents, including other potential slots -->
  </component>
</template>

Maybe something like v-passthrough, v-dissolve or v-hoist might work better?

[adamdehaven]

This original example whereby this template:

<Tooltip v-skip="!disabled">
  <button :disabled="disabled">Submit</button>
  <template #content>
    <em>The button is disabled because ...</em>
  </template>
</Tooltip>

...renders this HTML:

<button :disabled="disabled">Submit</button>

seems a bit odd to me.

It’s rendering the default slot content, but then other slots (content here) are discarded?

[MiniDigger]

the whole component is discarded and only its children (aka the default slot) are kept.

[adamdehaven]

What I’m essentially pointing out is that the default slot is being treated “special” here.

Non-default slot content is technically still comprised of child nodes.

[adamdehaven]

MyComponent

<template>
  <div>
    <slot name=“default” />
    <slot name=“content” />
  </div>
</template>

Usage

<template>
  <MyComponent v-skip=“conditional”>
    <template #default>
      <button>Foo</button>
    </template>
    <template #content>
      <button>Bar</button>
    </template>
  </MyComponent>
</template>

Result

<button>Foo</button>

With this simplified example, why would a sibling node be discarded? I understand the premise here; just saying it may lead to some unexpected use-cases as there is no requirement to have a slot named default in a parent component that is slottable.

[Justineo]

The content slot is specifically for <MyComponent> so it doesn't make sense to keep it if <MyComponent> is gone. We need a fallback content when the wrapper is gone and it has to be the default slot.

And of course it will lead to some unexpected cases for certain component API design. Take the <Tooltip> example, if we are using default slot to render the tooltip content but a trigger slot to render the anchor target, then using v-skip on <Tooltip> may lead to unexpected result. But I guess there has to be some trade-offs here.

[adamdehaven]

Docs will be key here; but yes the trade off makes sense 👍🏼

[altrusl]

This is a very rare case and 'userland' component does the job quite well
Extra v- directives complicate the framework and make it less attractive and intuitive

[dbzx10299]

This is a great idea and v-skip makes the most sense to me since you are essentially skipping a node in a tree and not unwrapping it.

[edison1105]

Edge Cases to Consider for v-contents

Let’s assume it’s called v-contents.

1. Scoped Slots Handling

Basic Usage Scenario

<Table v-contents="foo">
  <template #row="{ item }">
    <td>{{ item.name }}</td>
    <td>{{ item.age }}</td>
  </template>
</Table>

• When foo is false, where does the scope { item } come from?
• The scope data originally provided by the Table component would be lost

Nested Scoped Slots

<DataProvider v-contents="foo">
  <template #default="{ data }">
    <List>
      <template #item="{ item }">
        {{ data.title }} - {{ item.name }}
      </template>
    </List>
  </template>
</DataProvider>

• The outer scope ({ data }) would be lost
• May affect the normal rendering of inner components
• Breaks the original data flow

Dynamic Slots

<Component v-contents="foo">
  <template #[dynamicSlot]="slotProps">
    {{ slotProps.data }}
  </template>
</Component>

To address these issues, we need to:

• Clearly specify the principles for handling scoped slots in the RFC
• Consider providing a mechanism to preserve or pass through scope data
• Consider whether a special syntax is needed to handle these cases

This is a technical detail that requires special attention and may influence the final design of the directive.

2. Refs Handling

<div v-contents="foo" ref="wrapper">
  <span ref="content">content</span>
</div>

• Need to define ref behavior when outer element is skipped

3. DOM Properties and Styles

<div v-contents="foo" class="wrapper" :style="styles">
  <span>content</span>
</div>

• Whether to pass down class, style attributes when outer element is skipped
• How to handle potential conflicts if passed down

4. Combination with Other Directives

<div v-contents="foo" v-show="bar">
  <span>content</span>
</div>

• Consider interaction with v-show, v-if, v-for directives
• Define directive priority and execution order

5. Work with built-in components

Teleport

<teleport to="body" v-contents="foo">
  <div>teleported content</div>
</teleport>

Suspense

<Suspense v-contents="foo">
  <AsyncComponent />
</Suspense>

KeepAlive

<KeepAlive v-contents="foo">
  <component :is="currentComponent" />
</KeepAlive>

All these edge cases need careful consideration during implementation and should be clearly documented in the RFC. Some cases might require special handling or explicit behavior definitions.

[Justineo]

1. Scoped Slots Handling

Only default slots without accessing slot props are preserved.

2. Refs Handling

The ref value will be the same as if it's v-ifed out.

3. DOM Properties and Styles

No fall through, it's just the same as if you don't have this element or component in the template.

4. Combination with Other Directives

v-if -> v-skip -> v-show

5. Work with built-in components

I even think it can be compiled into two v-if branches: one with the wrapper and one without it. Therefore, I believe this might not require special handling for the built-in components.

[dbzx10299]

vNodes have a children property but not a parent property, this is one of the challenges building this. Another thing to note is that using server side rendering, it would be nice if this could walk the vnode ast and detect if a child vnode has a v-skip directive so that a single block of html can be rendered on the server.

I have ran into instances where I needed something like this and the whole point of having a directive like this is so that it doesn't need to be compiled into two v-if branches. In that case we might as well just continue to use v-if.