DEV Community: Frederik Dietz

Vue.js Mixins, extending components and High Order Components

Frederik Dietz — Sun, 03 May 2020 11:22:34 +0000

This is the first article in my series which doesn't really deal with component composition, but instead focuses on code reuse with various concepts including Mixins, extending existing components and even high order components. We want to focus on mixins first, since this is the simplest concept directly supported by Vue.js and then proceed to more advanced patterns.

Mixins are a way to reuse functionality in multiple Vue components. When a component uses a mixin, all options and functions will be "mixed" or "merged" into the component's own options. We differentiate between global and local mixins, whereas the former is used in the Vue instance.

Global Mixins

A global mixin is used by the Vue instance using the mixin property and makes it's options available to all components used by this Vue instance:

new Vue({
  el: '#demo',
  mixins: [MyMixin]
});

As an example we want to implement a very simple translation service. It should provide a translate function for all components to lookup translation strings.

Let's start with the Vue instance:

new Vue({
  el: '#demo',
  mixins: [Translate],
  data: {
    locale: "en"
  }
});

And the actual Translate mixing:

// some example translations of two languages
const TRANSLATIONS = {
  en: {
    firstName: "Firstname",
    age: "Age"
  },
  de: {
    firstName: "Vorname",
    age: "Alter"
  }
};

const Translate = Vue.mixin({
  methods: {
    translate(key) {
      return TRANSLATIONS[this.$root.locale][key];
    }
  },
  ready() {
    // default locale set to "en"
    this.$root.$set("locale", "en");
  }
});

The translate function looks for the translated string using the locale, configured by the Vue instance and the key. In case the Vue instance does not set the locale, we use the ready lifecycle hook to set it ourselves.

By mixing the Translate mixin with the Vue instance we can now call it's translate(key) function from other components. For our example we create a small card component which renders the first name and age:

Vue.component("card-profile", {
  template: "#card-profile-template",
  props: {
    firstName: String,
    age: String
  }
});

And the template uses the translate function:

<template id="card-profile-template">  
  <div>
    <h2>My Profile</h2>
    <div>
      {{translate("firstName")}}: {{firstName}}
    </div>
    <div>
      {{translate("age")}}: {{age}}
    </div>
  </div>
</template>

With the component in place we can render the demo app:

<div id="demo">
  <card-profile first-name="Michael" age="30" />
  <card-profile first-name="Lana" age="32" />
</div>

You can find the complete example on GitHub

Global mixins should only rarely be used since all options are mixed into all components which can quickly get out of hand. More often you might want to use a local mixin instead.

Local Mixins

A local mixin's options are only merged with the component using this mixin. This makes this approach much more manageable. For our example we want to build a small data loader mixin which loads data via AJAX request from a configurable url.

Here's the mixin:

const DataLoader = Vue.mixin({
  data() {
    return {
      loading: false,
      response: null
    }
  },
  methods: {
    load(url) {
      this.loading = true;
      return axios.get(url)
        .then(response => {
          this.response = response.data;
          this.loading = false;
        })
    }
  }
});

It provides a load method which uses axios again to fetch some data from a remote url. Additionally, the loading and response data is provided for you.

Let's use this mixin in our component:

Vue.component("article-card", {
  mixins: [DataLoader],
  template: "#article-card-template",
  created() {
    this.load("https://jsonplaceholder.typicode.com/posts/1")
  }
});

We use the mixin option to use the DataLoader and call the load function provided by the mixin in the created lifecyle hook.

The template for the article-card component is showing the data depending on the loading state.

<template id="article-card-template">  
  <div>
    <span v-if="loading">Loading...</span>
    <div v-else>
      <h2>{{response.title}}</h2>
      {{response.body}}
    </div>
  </div>
</template>

You can find the complete example on GitHub

There's one aspect of a mixin we haven't discussed yet. How intelligent is the actual merging strategy? In fact if your component has it's own state loading or response it would conflict with the mixin state and would certainly cause confusion. Same goes for methods, components and directive options: The component always has priority. When it comes to lifecyle methods, both will be called but the mixin's method will be called first.

There's a whole chapter dedicated to merging strategies in the Vue.js guide.

Extending components

Using a mixin is just one way to reuse code in Vue.js. One other way is to use the extends option instead. For our example think of a very complicated component which fetches some user data and renders a pretty user card. You are just reusing the component and cannot change the implementation. But using extends you can build a new component which reuses most code of the original component.

Let's have a look at our fancy user card component:

const BaseArticleCard = Vue.component("base-article-card", {
  props: ["id"],
  template: "#base-article-card-template",
  data() {
    return {
      loading: false,
      title: "",
      body: "",
      userId: ""
    }
  },
  computed: {
    articleTitle() {
      return `Article: ${this.title}`;
    }
  },
  methods: {
    load(id) {
      this.loading = true;
      return axios.get(`https://jsonplaceholder.typicode.com/posts/${id}`)
        .then(response => {
          this.title = response.data.title;
          this.body = response.data.body;
          this.userId = response.data.userId;
          this.loading = false;
        });
    }
  },
  created() {
    this.load(this.id);
  }
});

I've used very similar code again to fetch the data via axios request library in the created hook via a load method. An id prop is used to identify the user for the request url.

The template then renders the user data depending on the loading state:

<template id="base-article-card-template">  
  <div class="article-card">
    <div v-if="loading">Loading...</div>
    <div v-else>
      <h2>{{title}}</h2>
      {{body}}
    </div>
  </div>
</template>

Now, imagine your own card component renders things slightly different. We can simply extend the component:

Vue.component("advanced-article-card", {
  extends: BaseArticleCard,
  template: "#advanced-article-card-template"
});

And then use a different template:

<template id="advanced-article-card-template">  
  <div class="article-card">
    <div v-if="loading">Loading...</div>
    <div v-else>
      <h2>{{articleTitle}}</h2>
      <p>Written by User ID: {{userId}}</p>
      {{body}}
    </div>
  </div>
</template>

You can find the complete example on GitHub

All options of the base component are reused in our new component, except the template where we decided to use our own.

To be honest with you, I had quite a hard time to come up with a sensible example for the Vue.extend feature. In almost all cases I come up with I personally prefer using mixins instead.

High Order Components

HOCs are components which return another component but extend the behaviour in a reuseable way. Our data loading component is again a good example to get our feet wet with High Order components. So, we want to extend the card component from the previous example with a HOC which fetches data and passes this data along to the component via props.

In our next example we need to use the vue-cli to generate a project using SFC.

The usage of a HOC looks like this:

// our component
import ArticleCard from "./components/ArticleCard.vue";
// the HOC function
import withLoader from "./withLoader";
// our combined resulting component
const ArticleCardWithLoader = withLoader(ArticleCard);

We implement a withLoader function which gets an ArticleCard component as input and returns the extended component ArticleCardWithLoader.

The implementation of the HOC looks similar to our previous examples:

// withLoader.js
import Vue from "vue";
import axios from "axios";

const withLoader = component => {
  return Vue.component("with-loader", {
    render(createElement) {
      return createElement(component, {
        props: {
          loading: this.loading,
          title: this.title,
          body: this.body
        }
      });
    },
    props: ["id"],
    data() {
      return {
        loading: false,
        title: "",
        body: "",
      }
    },
    methods: {
      load(id) {
        this.loading = true;
        return axios.get(`https://jsonplaceholder.typicode.com/posts/${id}`)
          .then(response => {
            this.title = response.data.title;
            this.body = response.data.body;
            this.loading = false;
          });
      }
    },
    created() {
      this.load(this.id);
    }
  });
};

export default withLoader;

The withLoader function returns a new component which wraps our component and passes along some props including loading, title and body in the render function.

Our card component can then render this data, without knowing that it is wrapped by a HOC component:

<template>
  <div class="article-card">
    <div v-if="loading">Loading...</div>
    <div v-else>
      <h2>{{title}}</h2>
      {{body}}
    </div>
  </div>
</template>

<script>
export default {
  props: {
    loading: Boolean,
    title: String,
    body: String
  }
};
</script>

You can find the complete example on GitHub

There are a lot of open questions here. For example in the current implementation we cannot just pass along some additional props without changing the HOC component since it needs to pass these props
explicitly. It's not really a problem for such a small example, but it shows that there is no easy way to compose components using generics HOCs with Vue.js built-in functionality.

Summary

There's an ongoing discussion in the Vue.js community about the use of HOCs, or High Order Components. These are quite popular in the React community actually.

If you are interested in the discussion and props and cons of using HOCs in Vue.js, I can highly recommend this article
by Bogna Knychała and the vue-hoc project which implements some useful helpers to work around these problems.

Personally, I prefer to use slots and scoped slots instead of HOCs but your mileage may vary.

Vue.js Dynamic Component Rendering

Frederik Dietz — Tue, 31 Mar 2020 13:42:13 +0000

In the last chapter have already seen quite a few examples of flexible components using render functions which give us a lot of power. But, since rendering a component dynamically via it's name is such a typical use case there is built-in support for that in Vue.js.

In this chapter we discuss the usage of the <component> tag.

Using the `<component is>` feature

As an example we use a tab navigation where the content of a tab is rendered dynamically.

Example 1

Let's start with the tab content:

Vue.component('tab-home', {
  template: '<div>Home component</div>'
});

Vue.component('tab-posts', {
  template: '<div>Posts component</div>'
});

Vue.component('tab-archive', {
  template: '<div>Archive component</div>'
});

I'm using a common name prefix tab- here to make it easier to lookup these components later.

Now, to render the component dynamically we use the <component> tag and give it a name via the is prop:

<component is="tab-home"></component>

It is that simple! Vue then lookups the component referenced by that String and renders it in place of the <component> tag.

Now, this example is still static, let make it more dynamic. First we need to manage all our tabs in the Vue.js app:

new Vue({
  el: '#demo',
  data: {
    currentTab: 'Home',
    tabs: ['Home', 'Posts', 'Archive']
  },
  computed: {
    currentTabComponent: function () {
      return 'tab-' + this.currentTab.toLowerCase()
    }
  }
});

We use the tabs for the list of all tabs we want to render and the currentTab to maintain the selection. The actual component's name is concatenated as a computed property currentTabComponent.

Next we look into the markup to render the tabs:

<div id="demo">
  <ul class="tab-list">
    <li
      v-for="tab in tabs"
      :key="tab"
      >
      <a
        :class="['tab', { active: currentTab === tab }]"
        @click="currentTab = tab">
        {{tab}}
      </a>
    </li>
  </ul>

  <component
    :is="currentTabComponent"
    class="tab-content">
  </component>
</div>

You can find the complete example on GitHub

We use a v-for directive to render a list of tabs using the currentTab to set the active class. The @click event is used to change the currentTab state. Clicking on a tab will change the background-color to visually indicate the active state.

The <component> uses the currentTabComponent computed property to render the active tab content.

Note, how it passes along the class prop to the actual component it renders. Nice!

Summary

The <component> tag is quite a powerful feature and in some use cases it might be easier to use instead of slots and custom code.

Vue.js Functional Components

Frederik Dietz — Mon, 23 Mar 2020 09:26:28 +0000

In the previous article we looked into headless components and how to achieve maximum flexiblity by separating the logic from the rendering. In this article we focus on functional components.

In most Vue.js apps there are a lot of components which do not really do anything besides rendering a template. They do not contain any business logic or make use of the component lifecycle.

In this case using a functional component might remove some unnecessary boilerplate and the component renders faster too!

You can think of a functional component to be the equivalent of a function which takes a render context as input and returns rendered HTML.

In this chapter we explore how and when to use functional components and the pros and cons of them.

Functional components using the vue-cli and SFC

Let's start with a new default project created via the vue-cli, following the official guide
using the default setup.

It should generate an App.vue and a HelloWorld.vue file for you which we start modifying for our example.

The App.vue file imports the HelloWorld component which has a msg prop and a @click event. We use this event to increment a clickCount.

<template>
  <div id="app">
    <img src="./assets/logo.png">
    <HelloWorld msg="Welcome to Your Vue.js App" @click="clickCount+=1">
      <p>I was clicked: {{clickCount}}</p>
    </HelloWorld>
  </div>
</template>

<script>
import HelloWorld from "./components/HelloWorld.vue";

export default {
  name: "app",
  data() {
    return {
      clickCount: 0
    };
  },
  components: {
    HelloWorld
  }
};
</script>

The HelloWorld component consists of a template only:

<template functional>
  <div class="hello">
    <h1>{{ props.msg }}</h1>
    <button @click="listeners.click">Click me</button>
    <slot></slot>
  </div>
</template>

You can find the complete example on GitHub

Note, that the template has an additional functional attribute. This flag turns the component into a functional component. Additionally, Vue.js changes how you access the context of the component. Where you previously accessed props like msg directly, you now need to use prop.msg instead and events via listeners.click.

All these changes in usage are necessary since a functional component has no instance or state and therefore no this or data.

If you need to create lots of small mainly visual components, as for example a Heading, functional components make a lot of sense.

Functional components using Vue.component and render function

There is another way of using functional components using the Vue.component function:

Vue.component("hello-world", {
  // leanpub-start-insert
  functional: true,
  // leanpub-end-insert
  render(createElement, {data, listeners, slots}) {
    return createElement("div", { class: "hello" }, [
      createElement('h2', data.attrs.msg),
      createElement('button', {
        on: {
          click: listeners.click
        }
      }, 'Click me'),
      slots().default
    ]);
  }
});

You can find the complete example on GitHub

The functional attribute is used together with a render function. We've looked into these render functions before in the previous chapter about headless components.

Every argument passed along to the render function is what we call the render context. It includes data, listeners, props, slots, parent, injections, etc. In our example we used JavaScript destructuring to only pick what we need in our function. You can read more background about render functions in the official Vue.js guide.

Compared to the first example using SFC it looks like a lot of boilerplate code. But, this can be much cleaner when using JSX instead.

Functional components using Vue.component and JSX

In order to use JSX we recommend to use the vue-cli with the default setup from the first example. It supports JSX out of the box - no configuration required!

Let's have a look how our component looks like now:

<script>
export default {
  name: "HelloWorld",
  functional: true,
  render(h, { data, listeners, children }) {
    return (
      <div class="hello">
        <h1>{data.attrs.msg}</h1>
        <button onClick={listeners.click}>Click me</button>
        {children}
      </div>
    );
  }
};
</script>

You can find the complete example on GitHub

Since we use a SFC component again we use a script tag for the JavaScript code. The functional attribute together with the render function is used again, but this time the render implementation is using JSX syntax.

When compared to normal Vue.js templates we use single curly braces instead of the mustache syntax and for events we use onClick instead of v-on:click. But, this is only scratching the surface here. The interesting thing about JSX is that everything in these curly braces is all JavaScript and converted to JavaScript functions via the h argument.

Here's an example of rendering a list in JSX:

const listItems = props.numbers.map(number =>
  <li>{number}</li>
);
return (
  <ul>{listItems}</ul>
);

Summary

I'm not recommending to always use JSX now, but it certainly has it strengths for some use cases and it is therefore beneficial to know the limitations of the Vue.js template language and the pros and cons of JSX compared to that.

I personally favor using Vue.js templates for almost all components. The only reason for me to use JSX is when dealing with very dynamic component creation where the number of v-if and v-else makes the code less readable.

Vue.js Headless Component

Frederik Dietz — Mon, 23 Mar 2020 09:23:33 +0000

In the previous article we looked into scoped slots which we will now explore further by introducing the concept of "headless" or how they are sometimes called "renderless" components.

Headless components aim for maximum flexibility by completely separating the logic from the rendering. This is especially useful when a component contains a large amount of business logic.

Let's look into a typical example made famous by Kent Dodds when he introduced these concepts more deeply in the context of React where render props are used for similar use cases.

The Toggle Component

The Toggle component encapsulates logic to toggle a Boolean state useful for various kinds of scenarios including switch components, expand/collapse scenarios, accordions, etc.

Sometimes it helps to figure out the component requirements when fleshing out first how the component will be used:

<Toggle @change="handleChange">
  <template v-slot:default="{active, toggle}">
    <button @click="toggle" class="button">Toggle</button>
    <div>{{active ? "yes" : "no"}}</div>
  </template>
</Toggle>

We start with a button which toggles the active state. The active and toggle props are passed along via a scoped slot as seen already in the previous chapter. The change event is useful to users of the Toggle component to get notified of changes.

The template of our Toggle only really needs to use the slot mechanism to pass these props along:

<template id="toggle-template">  
  <slot :active="active" :toggle="toggle"></slot>
</template>

And the Toggle component itself defines the active state and the toggle method which is responsible for toggling the state and emitting the change event.

Vue.component("Toggle", {
  template: "#toggle-template",
  data() {
    return {
      active: false
    }
  },
  methods: {
    toggle() {
      this.active = !this.active;
      this.$emit("change", this.active);
    }
  }
});

And the Vue instance implements the handleChange method:

new Vue({
  el: '#demo',
  methods: {
    handleChange(active) {
      console.log("changed to ", active)
    }
  }
});

You can find the complete example on GitHub

The example by itself is not really showing the flexibility of the headless component pattern. But, it exemplifies the complete separation of state management logic and the actual rendering. The latter is completely up to the client to implement.

Reusing the component together with a Switch Component

Let's implement another example but this time with a more complex component: the switch component.

<Toggle @change="handleChange">
  <template v-slot:default="{active, toggle}">
    <switch-toggle :value="active" @input="toggle"></switch-toggle>
    <div>{{active ? "yes" : "no"}}</div>
  </div>
</Toggle>

Note, how the usage did not change at all. The only difference is that instead of a button we have a switch toggle.

Example 1

The switch component's implementation is not important for this example, but let's go over it quickly. First of all: It is a controlled component and has no internal state.

Vue.component("SwitchToggle", {
  template: "#switch-template",
  props: {
    value: {
      type: Boolean,
      default: false
    }
  }
});

And the template:

<template id="switch-template">  
  <label class="switch">
    <input type="checkbox" :checked="value" @change="$emit('input', $event.target.checked)"/>
    <div class="switch-knob"></div>
  </label>
</template>

The value prop is bound to the checked attribute and on change we emit an input event with the current state.

Isn't it fantastic that we could reuse our Toggle component unchanged here even though the end result looks completely different?

There's one more thing! Since the Toggle component does not really render much besides the slot, we can simplify our code but using a render function instead of a template:

Vue.component("Toggle", {
  template: "#toggle-template",
  render() {
    return this.$scopedSlots.default({
      active: this.active,
      toggle: this.toggle
    })[0];
  },
  data() {
    return {
      active: false
    }
  },
  methods: {
    toggle() {
      this.active = !this.active;
      this.$emit("change", this.active);
    }
  }
});

You can find the complete example on GitHub

The component is now solely defined via JavaScript containing the business logic. No template used at all. Nice!

You can read up some more details in the Vue.js Guide.

Let's see how far we can go with our Toggle component and if we can make it even more flexible.

Expand/Collapse Component and Prop Collections

Our Toggle can be reused again for a completely different use case. We want to implement a simple expand/collapse toggle which looks like this.

Example 2

And we can achieve it by using markup only:

<Toggle @change="handleChange">
  <template v-slot:default="{active, toggle}">
    <div class="expandable">
      <h2 class="expandable__header">
        Heading 2
        <button class="expandable__trigger" @click="toggle" aria-expanded="active">
          <svg aria-hidden="true" focusable="false" viewBox="0 0 10 10">
            <rect v-if="active" height="8" width="2" y="1" x="4"/>
            <rect height="2" width="8" y="4" x="1"/>
          </svg>
        </button>
      </h2>
      <div v-if="active" class="expandable__content">
        Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, ...
      </div>
    </div>
  </div>
</Toggle>

You can find the complete example on GitHub

There is a lot going on here. So, let us break it down!

We define a header element which contains a button to toggle the state using the toggle prop. The active prop is used to conditionally render a div containing the expandable content.

Additionally, the active prop is used again to render a slightly different SVG icon depending on if the state is expanded or collapsed:

<svg aria-hidden="true" focusable="false" viewBox="0 0 10 10">
  <rect v-if="active" height="8" width="2" y="1" x="4"/>
  <rect height="2" width="8" y="4" x="1"/>
</svg>

Note, how the active prop is used with the v-if directive? This will either hide or show the vertical rectangle, which means the + icon is turned into a - icon.

You might have noticed the use of the aria attributes on the button and on the SVG icon. These are specifically used to support screen readers. The blog article Collapsible Sections by Heydon Pickering is an excellent introduction to using aria attributes and the example code in the blog article is the basis of the component you see here.

There's an opportunity here to generalize the Toggle component even more. We could always support the toggling action by providing a click event instead of a toggle. And the aria-expanded attribute could be somehow passed along, too.

Let's first check how the usage would look like after making these props available:

<Toggle @change="handleChange">
  <template v-slot:default="{active, togglerProps, togglerEvents}">
    <div class="expandable">
      <h2 class="expandable__header">
        Heading 2
        <button class="expandable__trigger" v-bind="togglerProps" v-on="togglerEvents" >
          <svg aria-hidden="true" focusable="false" viewBox="0 0 10 10">
            <rect v-if="active" height="8" width="2" y="1" x="4"/>
            <rect height="2" width="8" y="4" x="1"/>
          </svg>
        </button>
      </h2>
      <div v-if="active" class="expandable__content">
        Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, ...
      </div>
    </div>
  </div>
</Toggle>

The scoped slot now provides active, togglerProps and togglerEvents and the toggle is gone. The togglerProps is actually not a single prop but an object with multiple props. Is is therefore convenient to use v-bind to apply all props automatically. Same goes for the togglerEvents where we have to use v-on instead, since these are events.

The implementation of Toggle component slightly changes to pass along these new props:

Vue.component("Toggle", {
  render() {
    return this.$scopedSlots.default({
      active: this.active,
      toggle: this.toggle
      togglerProps: {
        'aria-expanded': this.active
      },
      togglerEvents: {
        'click': this.toggle
      }
    })[0];
  },
  data() {
    return {
      active: false
    }
  },
  methods: {
    toggle() {
      this.active = !this.active;
      this.$emit("change", this.active);
    }
  }
});

You can find the complete example on GitHub

The scoped slot passes along the togglerProps with the aria-expanded attribute and the togglerEvents with the click event to toggle the state.

We achieved not only an increased reusability but additionally made it more user-friendly by managing the aria-expanded attribute automatically.

Summary

In this article we looked into Headless or Renderless components using Vue.js scoped lots and showed how to create highly reusable components which focus only on the logic and leave the rendering to the client.

It is fascinating that the Vue.js slot mechanism can be used for such a large variety of use cases. And it will be interesting to watch the community come up with even more ideas.

If you liked this article you can find much more content in my Vue.js Component Patterns Book. Its free :-)

Vue.js Component Composition with Scoped Slots

Frederik Dietz — Sun, 16 Jun 2019 12:53:48 +0000

In the previous post we looked into slots and named slots to compose our components and content in a very flexible way.
There's one catch though we have not discussed. The content we pass to our slot is in the context of the parent component and not the child component. This sounds quite abstract, let's build an example component and investigate the problem further!

List of Items Example

Probably the most canonical example for this kind of scenario is a todo list which renders for each todo a checkbox with name.

Example 1

<div id="demo">
  <div class="list">
    <div v-for="item in listItems" key="item.id" class="list-item">
      <input type="checkbox" v-model="item.completed" class="list-item__checkbox" />
      {{item.name}}
    </div>
  </div>
</div>

new Vue({ 
  el: '#demo',
  data: {
    listItems: [
      {id: 1, name: "item 1", completed: false},
      {id: 2, name: "item 2", completed: false},
      {id: 3, name: "item 3", completed: false}
    ]
  }
});

In the next step we refactor this code into a reusable list component and our goal is to leave it up to the client of the component to decide what and how to render the list item.

Refactor to Reusable List component

Let's start with the implementation of the List component:

Vue.component("List", {
  template: "#template-list",
  props: {
    items: {
      type: Array, 
      default: []
    }
  }
});

<template id="template-list">  
  <div class="list">
    <div v-for="item in items" class="list-item">
      <slot></slot>
    </div>
  </div>
</template>

Following our previous examples we use the default slot to render a list item.

And now make use of our new component:

<div id="demo">
  <List :items="listItems">
    <div class="list-item">
      <input type="checkbox" v-model="item.completed" class="list-item__checkbox" />
      <div class="list-item__title">{{item.name}}</div>
    </div>
  </List>
</div>

But, when trying this example we run into a Javascript error message:

ReferenceError: item is not defined

It seems we cannot access item from our slot content. In fact the content we passed runs in the context of the parent and not the child component List.

Let's verify this by printing the total number of items in our List component using the listItems data defined in our Vue instance.

<div id="demo">
  <List :items="listItems">
    <div class="list-item">
      {{listItems}}
    </div>
  </List>
</div>

That works because we run in the context of the parent component which is in this example the Vue instance. But, how can we pass the item data from our child <List> to our slot? This is where "scoped slots" come to the rescue!

Our component must pass along item as a prop to the slot itself:

<template id="template-list">  
  <div class="list">
    <div v-for="item in items" class="list-item">
      <slot :item="item"></slot>
    </div>
  </div>
</template>

Note, that it is important to pass this with a binding :item instead of only item!

Okay let's try this again:

<div id="demo">
  <List :items="listItems">
    <div slot-scope="slotProps" class="list-item">
      <input type="checkbox" v-model="slotProps.item.completed" class="list-item__checkbox" />
      <div class="list-item__title">{{slotProps.item.name}}</div>
    </div>
  </List>
</div>

This time we use the slot-scope attribute and assign the name slotProps to it. Inside this scoped slot we can access all props passed along via this slotProps variable.

In Vue.js 2.5.0+, scope is no longer limited to the <template> element, but can instead be used on any element or component in the slot.

Extending the rendering of the list item

Now that we know how to pass data along we are free to extend the list item with some new functionality without changing the List component. It would be awesome if we could remove a todo item!

First of all we define the Vue app with a method to remove a todo item:

new Vue({ 
  el: '#demo',
  data: {
    listItems: [
      {id: 1, name: "item 1", completed: false},
      {id: 2, name: "item 2", completed: false},
      {id: 3, name: "item 3", completed: false}
    ]
  },
  methods: {
    remove(item) {
      this.listItems.splice(this.listItems.indexOf(item), 1);
    }
  }
});

We use the Javascript splice function to remove the item using it's index from listItems.

Next, we use this method when rendering the list item:

<template slot-scope="slotProps" class="list-item">
  <input type="checkbox" v-model="slotProps.item.completed" class="list-item__checkbox" />
  <div class="list-item__title">{{slotProps.item.name}}</div>
  <button @click="remove(slotProps.item)" class="list-item__remove">×</button>
</template>

We add a button with a click event which calls our previously defined remove function. That's it!

Using Destructuring for the `slot-scope`

We can further simplify this template by using a modern Javascript trick on the slot-scope attribute.

Here's an example of using Javascript "destructuring" to access an attribute of an object:

const item = slotProps.item;
// same as 
const { item } = slotProps;

Instead of using the value slotProps we can now access the item directly.

Let's use this in our template:

<template slot-scope="{item}" class="list-item">
  <input type="checkbox" v-model="item.completed" class="list-item__checkbox" />
  <div class="list-item__title">{{item.name}}</div>
  <button @click="remove(item)" class="list-item__remove">×</button>
</template>

This is easier to read because we can directly use the item variable instead of always going via slotProps.item.

Summary

In this chapter we used scoped slots to allow the parent to access data from the child. This gives us lots of new possibilities which weren't possible before. This feature is especially useful in scenarios where you want to leave the rendering of the slot content to the user of the component. In our case the list component is very reusable by decoupling the rendering of the list items.

You can find the complete examples on Github.

If you like this post also check out my new course Vue.js Component Patterns Course.

Stay tuned for my upcoming post about headless components!

Vue.js Component Composition with Slots

Frederik Dietz — Sun, 16 Jun 2019 12:49:19 +0000

In the previous post we introduced the Vue.js component model and saw how to pass data to child components via props and how components can emit events up their parents.

In this chapter we focus on slots which give your components even more flexibility by injecting content into child components.

For this chapter we use a modal dialog as an example.

Slots as Content Placeholders

We start with the smallest possible modal dialog implementation where the rendering of the modal is done using a v-if directive with the showModal variable.

new Vue({
  el: "#demo",
  data: {
    showModal: false
  }
});

The showModal value is set to true on button click:

<div id="demo">
  <modal v-if="showModal" @close="showModal = false">
    <h2>Modal Header</h2>
    <p>This is a paragraph inside the modal.</p>
  </modal>
  <button @click="showModal = true">Show Modal</button>
</div>

Our modal component children consist of some example HTML heading and paragraph we'd like to show inside the modal dialog.

Additionally, we listen to the @close event in case the user closes the modal dialog by pressing the close button.

Let's have a look at the component:

<template id="template-modal">
  <div class="modal-background" @click.self="$emit('close')">
    <div class="modal-container">
      <div class="modal-body">
        <slot></slot>
      </div>
      <div class="modal-footer">
        <button @click="$emit('close')">Close</button>
      </div>
    </div>
  </div>
</template>

The modal-body contains a slot component which acts as a placeholder for our content we passed along above. It will not be visible in the browser DOM and will be replaced with our content.

Screenshot of Chrome Devtools Elements Tab

The modal-background class used to render a darkened overlay underneath the modal dialog. Additionally, it emits a click event to close the dialog. The self event modifier is used to make sure the event is only emitted when clicking the background and not when clicking the modal dialog itself.

Named Slots

In our previous example we used the "default slot" to pass along all content to our modal component. In the next example we improve the modal dialog component further by using "named slots" which enables users of the component to inject content in multiple places.

In order to become more flexible, we introduce named slots for the header, body and footer. Here is the definition of our markup:

<template id="template-modal">
  <div class="modal-background" @click.self="$emit('close')">
    <div class="modal-container">
      <div class="modal-header">
        <slot name="header"></slot>
      </div>
      <div class="modal-body">
        <slot name="body"></slot>
      </div>
      <div class="modal-footer">
        <slot name="footer">
          <button @click="$emit('close')">Close</button>
        </slot>
      </div>
    </div>
  </div>
</template>

Note the usage of the name attribute for each slot and how each slot is wrapped in another div element. The component has complete control of the styling by using specific CSS classes modal-header, modal-body and modal-footer. And the user of the component can focus on the content only.

The usage of these named slots is quite similar to the default slot:

<modal v-if="showModal" @close="showModal = false">
  <h2 slot="header">Modal Header</h2>
  <div slot="body">Modal Body</div>
</modal>

We can use whatever HTML element we want for our content and use the slot attribute to select the appropriate slot we want to use. This not only includes HTML elements but also other Vue.js components.

Note, that the footer slot is not used in this example. By default the existing slot content will be used. In our case the footer slot is defined like this:

<slot name="footer">
  <button @click="$emit('close')">Close</button>
</slot>

So, we still have our Close button as is.

Summary

In this chapter we looked into slots and named slots to compose our components and content in a very flexible way. Stay tuned for my upcoming post on scoped slots!

If you like this post also check out my new course Vue.js Component Patterns Course.

Introduction to Components with Vue.js

Frederik Dietz — Sun, 21 Apr 2019 18:00:50 +0000

In this article I'd like to introduce you to the Vue.js component model and show the benefits of component reuse and
encapsulation.

If you don't know your way around Vue.js yet, I can highly recommmend the official Vue.js guide.

But, please don't be afraid of diving right into this article with me. I will point you to the relevant official documentation to give you some more background and a chance to read up on some more background material.

We will start with a simple example component and gradually improve its functionality.

Example 1 - Who doesn't like cats?

The HTML for this card component consists of a large image area and body with some text:

<div id="demo">
  <div class="image-card">
    <img class="image-card__image" src="cat.jpg" />
    <div class="image-card__body">
      <h3 class="image-card__title">Striped Tiger Cat</h3>
      <div class="image-card__author">Image by @lemepe</div>
    </div>
  </div>
</div>

We use the root HTML element with the demo id as our element to initiate Vue:

new Vue({ el: '#demo' })

What did we achieve? We used Vue.js to render this image card. But we can't really reuse this code as is and we don't want to copy and paste and thereby duplicating code.

The solution to our problem is to turn this into a component.

Components can be reused

So, let's separate the image card from the remaining Vue.js application.

First we introduce a template element with all the image card content:

<template id="template-image-card">
  <div class="image-card">
    <img class="image-card__image" src="cat.jpg" />
    <div class="image-card__body">
      <h3>Striped Tiger Cat</h3>
      <div class="image-card__author">Image by @lemepe</div>
    </div>
  </div>
</template>

And we define the component with Vue.component and reference our template id template-image-card:

Vue.component('image-card', {
  template: "#template-image-card"
})

This is again wrapped in an HTML root element:

<div id="demo">
  <image-card></image-card>
  <image-card></image-card>
</div>

And then instantiated:

new Vue({ el: '#demo' })

And voila! We have two cats :-)

Example 2 - two cats!

Now, two cats are obviously better than one cat and we showed that we can have several instances of our image-card component on the same page.

We now have the means to reuse this component in our app. And if you think about it, it's actually quite remarkable that this includes our HTML, CSS and Javascript code all wrapped up in a component.

But still, this component is not very useful, isn't it? It is just not flexible enough! It would be awesome if we could change
the image and text body for each component.

Passing data to child components as props

In order to customize the component's behaviour, we will use props.

Let's start with how we want to use our component:

<div id="demo">
  <image-card image-src="cat1.jpg" heading="Striped Tiger Cat" text="Image by @lemepe"></image-card>
  <image-card image-src="cat2.jpg" heading="Alternative Text" text="alternative subtitle"></image-card>
</div>

We introduce three new props image-src, heading, and text. When using the component these will be passed along as HTML attributes.

The prop definition of our component comes next:

Vue.component('image-card', {
  template: "#template-image-card",
  props: {
    heading: String,
    text: String,
    imageSrc: String
  }
});

Note, how the prop imageSrc is written in camelCase whereas the HTML attributes is using a dash image-src. You can read more about props in the official Vue.js Guide.

And the accompanying template uses this props in the camelCase format again:

<template id="template-image-card">
  <div class="image-card">
    <img class="image-card__image" :src="imageSrc" />
    <div class="image-card__body">
      <h3>{{heading}}</h3>
      <div class="image-card__author">{{text}}</div>
    </div>
  </div>
</template>

Let's have a look at the result:

Example 3 - image cards with props

It worked! We have used two instances of our image-card component with different props.

Isn't it nice that we can render a component differently using props as inputs?

Components have state

In my typical day job a product manager would most probably note that the image-card by itself looks quite nice with the cats and such. But, it is not really engaging yet. How about we let users like our cat and we could then keep a count of which cat had the most likes?

Components can have state using the data attribute:

  Vue.component('image-card', {
    template: "#template-image-card",
    props: {
      heading: String,
      text: String,
      imageSrc: String
    },
    data: function () {
      return {
        count: 0
      }
    }
  });

Note, that data is returning a function instead of only a Javascript object data: { count: 0 }.
This is required, so that each component instance can maintain an independent copy of the returned data.
Read more about this in the Vue.js Guide.

Our template uses this count:

<template id="template-image-card">
  <div class="image-card">
      <img class="image-card__image" :src="imageSrc" />
    <div class="image-card__body">
        <h3 class="image-card__heading">{{heading}}</h3>
      <div class="image-card__author">{{text}}</div>
      <button class="image-card__heart" @click="count++">
        <svg viewBox="0 0 32 29.6">
          <path d="M16,28.261c0,0-14-7.926-14-17.046c0-9.356,13.159-10.399,14-0.454c1.011-9.938,14-8.903,14,0.454 C30,20.335,16,28.261,16,28.261z"/>            
        </svg>
      </button>
      <div class="image-card__count" v-if="count > 0">{{count}}</div>
    </div>
  </div>
</template>

Example 4 - image card with state

We use an SVG element to render a little heart and on the click event we increment the count by 1. A little count is displayed next to the heart with the current count value.

If you are more interested in working with SVG, have a look in the Vue.js Cookbook for more information.

Note, that each component instance has its own local state of count which can be changed independently from the other component's count.

Whereas in the previous example we only encapsulated the HTML code and made it more flexible with props. We now also encapsulate some business logic to keep count.

Whereas props are the input parameters of our component, the state is something internal to the component and is hidden from a user of our component's code. We could change the name of our variable from count to clickCount and a user of our component wouldn't even need to know. This is awesome because we can keep improving our component without breakings our user's code.

Sending messages to parents with events

Now that we know how to pass data down to children and how to encapsulate state. There one thing missing: How can we get data back from a child?

In Vue.js we can emit a custom event from the component to it's parent which listens to that specific event. This event can additionally pass along data.

In our example we can use $emit to send an event called change with data to the parent:

Vue.component('image-card', {
  template: "#template-image-card",
  props: {
    heading: String,
    text: String,
    imageSrc: String
  },
  data: function () {
    return {
      count: 0
    }
  },
  methods: {
    handleClick() {
      this.count++;
      // leanpub-start-insert
      this.$emit("change", this.count);
      // leanpub-end-insert
    }
  }
});

We defined the method handleClick which not only increments our count state, but additionally uses $emit to send a message to our parent. The handleClick is called in the on click event of our heart:

<template id="template-image-card">
  <div class="image-card">
    <img class="image-card__image" :src="imageSrc" />
    <div class="image-card__body">
        <h3 class="image-card__heading">{{heading}}</h3>
      <div class="image-card__author">{{text}}</div>
      <button class="image-card__heart" @click="handleClick">
        <svg viewBox="0 0 32 29.6">
          <path d="M16,28.261c0,0-14-7.926-14-17.046c0-9.356,13.159-10.399,14-0.454c1.011-9.938,14-8.903,14,0.454 C30,20.335,16,28.261,16,28.261z"/>            
        </svg>
      </button>
      <div class="image-card__count" v-if="count > 0">{{count}}</div>
    </div>
  </div>
</template>

Now the parent template can use this to listen to the change event to increment a totalCount:

<div id="demo">
  <image-card image-src="cat.jpg" heading="Striped Tiger Cat" text="Image by @lemepe" @change="handleChange"></image-card>
  <image-card image-src="cat.jpg" heading="Alternative Text" text="alternative subtitle" @change="handleChange"></image-card>
  <p>Total Count: {{totalCount}}</p>
</div>

Together with the Vue.js instance to keep track of a totalCount:

new Vue({
  el: '#demo',
  data: {
    totalCount: 0
  },
  methods: {
    handleChange(count) {
      console.log("count changed", count);
      this.totalCount++;
    }
  }
});

Note, that the parent doesn't know about the component's internals. It just knows that there's a change event available and that the message sends the component's count.

The event emitted via this.$emit("event") is only send to the parent component. It will not bubble up the component hierarchy similar to native DOM events.

Summary

In this article we explored the base concepts of a component model. We discussed component reuse and encapsulation,
how to use props to pass data to children and how to emit events to pass messages to the parent.

If you like this post also check out my new course Vue.js Component Patterns Course.

DEV Community: Frederik Dietz

Vue.js Mixins, extending components and High Order Components

Global Mixins

Local Mixins

Extending components

High Order Components

Summary

Vue.js Dynamic Component Rendering

Using the <component is> feature

Summary

Vue.js Functional Components

Functional components using the vue-cli and SFC

Functional components using Vue.component and render function

Functional components using Vue.component and JSX

Summary

Vue.js Headless Component

The Toggle Component

Reusing the component together with a Switch Component

Expand/Collapse Component and Prop Collections

Summary

Vue.js Component Composition with Scoped Slots

List of Items Example

Refactor to Reusable List component

Extending the rendering of the list item

Using Destructuring for the slot-scope

Summary

Vue.js Component Composition with Slots

Named Slots

Summary

Introduction to Components with Vue.js

Components can be reused

Passing data to child components as props

Components have state

Sending messages to parents with events

Summary

Using the `<component is>` feature

Using Destructuring for the `slot-scope`