What exactly does v-bind:css="false" do, and where is it documented?

user_78202 0
Viewed 314

The Vue docs for JavaScript Hooks mention:

It’s ... a good idea to explicitly add v-bind:css="false" for JavaScript-only transitions so that Vue can skip the CSS detection. This also prevents CSS rules from accidentally interfering with the transition.

  1. Are there official docs for v-bind:css somewhere? (Note - I know what the v-bind directive does)
  2. What does "CSS detection" mean exactly, and where in the source is this done?
  3. What's an example of a CSS rule that would interfere with a transition, and technically how does this directive prevent that from happening?

The only other place I've seen this mentioned is in the Vue source code tests at vue/test/unit/features/transition/transition.spec.js, but as far as I can tell that test doesn't really check anything related to CSS.

vue.js
1 Answers

1. Are there official docs?

I haven't found any official docs for :css anywhere other than what you already found.

2. What does it do?

Investigating this myself, "CSS detection" is probably the wrong phrase, IMO it should read something like:

It’s ... a good idea to explicitly add v-bind:css="false" for JavaScript-only transitions so that Vue can skip applying the transition classes. This also prevents CSS rules from accidentally interfering with the transition.

The :css attribute is actually quite simple. It essentially turns on/off the adding of the v-enter, v-enter-to, v-leave, v-leave-to classes to the element being transitioned. We can see that in transition-util.js from the Vue source:

transition-util.js

if (def.css !== false) {
  extend(res, autoCssTransition(def.name || 'v'))
}

...

const autoCssTransition: (name: string) => Object = cached(name => {
  return {
    enterClass: `${name}-enter`,
    enterToClass: `${name}-enter-to`,
    enterActiveClass: `${name}-enter-active`,
    leaveClass: `${name}-leave`,
    leaveToClass: `${name}-leave-to`,
    leaveActiveClass: `${name}-leave-active`
  }
})

So if the css attribute is not set to false and the transition has a name attribute then this code will apply ${name}-enter, otherwise it applys v-enter.

3. Example Interference

Personally I have experienced interference when using custom hooks on the transition-group to apply custom classes. for example:

<transition-group @enter="enterHook">...

methods: {
  enterHook (el) {
    el.classList.add('custom-enter-class')
  }
}

Without the :css="false" attribute I experienced strange and inconsistent behaviour when adding/removing classes programmatically. This attribute made things much more robust.

user_66534260
Related