DEV Community: Giannis Koutsaftakis

How to use an object with v-model in Vue

Giannis Koutsaftakis — Sun, 19 Jan 2025 16:43:38 +0000

We all know and love v-model in Vue. It's the directive that enables two-way binding in Vue components. When manually implementing v-model for a custom component, here’s how it usually looks:

<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>

<template>
  <input
    :value="props.modelValue"
    @input="emit('update:modelValue', $event.target.value)"
  />
</template>

Notice that we don’t mutate the value of the modelValue prop inside the component. Instead, we emit the updated value back to the parent component, where the actual mutation happens. This is for a good reason: child components shouldn’t affect the parent’s state because it complicates data flow and makes debugging harder.

As stated in the Vue docs, you should not mutate a prop inside a child component. If you do, Vue will issue a warning in the console.

What about objects?
Objects and arrays are a special case in JavaScript because they are passed by reference. This means a component can directly mutate the nested properties of an object prop. However, Vue doesn’t issue warnings for mutations happening in nested object properties (it would incur a performance penalty to track these mutations). As a result, such unintended changes can lead to subtle and hard-to-debug issues in our app.

Most of the time, we use primitive values for v-model. However, in some cases, like building form components, we might need a custom v-model that works with objects. This raises an important question:

How do we implement a custom v-model for objects without falling into these pitfalls?

Exploring the problem

A first approach would be to use a writable computed property or the defineModel helper. However, both of these solutions have a significant drawback: they directly mutate the original object, which defeats the purpose of maintaining a clean data flow.

To illustrate the issue, let’s look at an example of a "form" component. This component is designed to emit an updated copy of the object back to the parent whenever a value in the form changes. We'll attempt to implement this using a writable computed property.

⚠️ In this example writable computed still mutates the original object.

<script setup lang="ts">
import { computed } from 'vue';
import { cloneDeep } from 'lodash-es';

type Props = {
  modelValue: { name: string; email: string; };
};

const props = withDefaults(defineProps<Props>(), {
  modelValue: () => ({ name: '', email: '' }),
});

const emit = defineEmits<{
  'update:modelValue': [value: Props['modelValue']];
}>();


const formData = computed({
  // The object that gets returned from the getter is still mutable
  get() {
    return props.modelValue;
  },
  // Commenting out the setter still mutates the prop
  set(newValue) {
    emit('update:modelValue', cloneDeep(newValue));
  },
});
</script>

This doesn't work as intended because the object that gets returned from the getter is still mutable, leading to unintended mutations of the original object.

The same thing happens with defineModel. Since update:modelValue is not emitted from the component and the object properties are mutated without any warning.

ℹ️ Throughout this article, I’ve used cloneDeep from lodash-es as an example of deep cloning objects. However, you can use any deep cloning method that suits your needs, such as structuredClone (built into modern browsers) or other utility libraries. The key takeaway is that cloning helps prevent unintended mutations when working with v-model and objects. Choose the approach that best fits your project!

The solution

The "Vue way" to handle this scenario is to use an internal reactive value for the object and implement two watchers:

A watcher to monitor changes to the modelValue prop and update the internal value. This ensures the internal state reflects the latest prop value passed from the parent.
A watcher to observe changes in the internal value. When the internal value is updated, it will emit a fresh, cloned version of the object back to the parent component to avoid directly mutating the original object.

To prevent an endless feedback loop between these watchers, we need to ensure that updates to the modelValue prop do not unintentionally re-trigger the watcher on the internal value.

<script setup lang="ts">
import { ref, watch, nextTick } from 'vue';
import { cloneDeep } from 'lodash-es';

type Props = {
  modelValue: { name: string; email: string; };
};

const props = withDefaults(defineProps<Props>(), {
  modelValue: () => ({ name: '', email: '' }),
});

const formData = ref<Props['modelValue']>(defaultFormData);

/**
 * We need `isUpdating` as a guard to prevent recursive updates from happening.
 * [Error] Maximum recursive updates exceeded in component <Component>. This means you have a reactive effect
 * that is mutating its own dependencies and thus recursively triggering itself. Possible sources include
 * component template, render function, updated hook or watcher source function.
 */
let isUpdating = false;

const emit = defineEmits<{
  'update:modelValue': [value: Props['modelValue']];
}>();

// Watch props.modelValue for data updates coming from outside
watch(
  () => props.modelValue,
  (nV) => {
    if (!isUpdating) {
      isUpdating = true;
      formData.value = cloneDeep(nV);
      nextTick(() => {
        isUpdating = false;
      });
    }
  },
  { deep: true, immediate: true }
);

// Watch local formData to emit changes back to the parent component
watch(
  formData,
  (nV) => {
    if (!isUpdating && nV !== props.modelValue) {
      emit('update:modelValue', cloneDeep(nV));
    }
  },
  { deep: true }
);
</script>

I know what you are thinking: "That's a lot of boilerplate!". Let's see how we can simplify this further.

Simplifying the solution with VueUse

Extracting this logic into a reusable composable is a great way to streamline the process. But here’s the good news: we don’t even need to do that! The useVModel composable from VueUse handles this for us!

VueUse is a powerful utility library for Vue, often referred to as the “Swiss army knife” of composition utilities. It’s fully treeshakable, so we can use only what we need without worrying about bloating our bundle size.

Here’s how our previous example looks when refactored to use useVModel:

<script setup lang="ts">
import { useVModel } from '@vueuse/core';
import { cloneDeep } from 'lodash-es';

type Props = {
  modelValue: { name: string; email: string; };
};

const props = withDefaults(defineProps<Props>(), {
  modelValue: () => ({ name: '', email: '' }),
});

const emit = defineEmits<{
  'update:modelValue': [value: Props['modelValue']];
}>();

// We need the `{ passive: true, deep: true }` options otherwise the prop will be mutated.
const form = useVModel(props, 'modelValue', emit, { clone: cloneDeep, passive: true, deep: true });
</script>

So much cleaner!

And that’s it! We’ve explored how to properly use an object with v-model in Vue without directly mutating it from the child component. By using watchers or leveraging the power of composables like useVModel from VueUse, we can maintain clean and predictable state management in our app.

Ηere’s a Stackblitz link with all the examples from this article. Feel free to explore and experiment.

Thanks for reading, and happy coding!

Vue 3 TypeScript code snippets and tips

Giannis Koutsaftakis — Mon, 01 Jul 2024 10:06:26 +0000

In this article, I've curated a collection of useful code snippets and tips that I frequently find myself searching for in the Vue docs or digging up from my existing codebase during development. Having all these snippets in one place should make it easier to reference and use them as quick copy-paste examples, ultimately saving valuable time when developing with Vue 3 and TypeScript.

Let's dive in!

Define a component

Here's an example of a component definition using the <script setup> syntax. The defineProps and defineEmits macros are used to declare the component's props and emitted events, respectively. The withDefaults helper allows us to set default values for the props. We can define this as a custom code snippet in our code editor to serve as a starting point when we're creating a new component.

<template>
  <div class="mb-4 flex items-center rounded bg-blue-50 p-4 text-blue-800">
    <div class="text-sm font-medium">
      {{ text }}
    </div>
    <button
      v-if="closeable"
      type="button"
      class="-m-1.5 ms-auto inline-flex size-8 items-center justify-center rounded p-1.5 hover:bg-blue-100"
      @click="close"
    >
      ✕
    </button>
  </div>
</template>

<script setup lang="ts">
defineOptions({
  name: 'SimpleComponent'
})

type Props = {
  text?: string
  closeable?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  text: '',
  closeable: false
})

const emit = defineEmits<{
  'click:close': [value: string]
}>()

const close = () => {
  emit('click:close', props.text)
}
</script>

Props validation

To validate props, we have to use the defineProps macro along with the PropType utility. This allows us to specify the type and a validator function that checks the prop's value. Here, the text prop is validated to ensure it starts with the letter 'T'.

import { type PropType } from 'vue'

defineProps({
  text: {
    type: String as PropType<string>,
    default: 'Test',
    validator(value: string) {
      return value.startsWith('T')
    }
  }
})

Define a template ref

Sometimes, we need a reference to a DOM element within our template. We can achieve this using ref.

<template>
  <div ref="header" class="text-4xl">Header text</div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const header = ref<HTMLElement | null>(null)
</script>

Define a component ref (get the type of a component)

Similarly, like DOM element refs, there are times when we require a reference to a component within our template. For that, we can use the InstanceType utility along with typeof. This ensures that our component references are correctly typed.

<template>
  <SimpleComponent ref="simpleComponentRef" :text="'Hello world!'" />
</template>

<script setup lang="ts">
import SimpleComponent from './SimpleComponent.vue'
import { ref } from 'vue'

type SimpleComponentType = InstanceType<typeof SimpleComponent>

const simpleComponentRef = ref<SimpleComponentType | null>(null)
</script>

Using the same technique we can extract the props type of a component:

type SimpleComponentTypeProps = InstanceType<typeof SimpleComponent>['$props']

In cases where the exact type of the component isn't available or isn't important, we can use the generic ComponentPublicInstance that Vue exposes for us, i.e:

import { type ComponentPublicInstance } from 'vue'

const simpleComponentRef = ref<ComponentPublicInstance | null>(null)

Generic component type

In scenarios where we need to store and render components dynamically, we can use the generic Component type. Such a scenario would be for example to store components in an object or an array so that we can render them dynamically in the template. By using shallowRef, we ensure that Vue doesn't complain with [Vue warn]: Vue received a Component that was made a reactive object..

<template>
  <Component :is="components.settings" />
</template>

<script setup lang="ts">
import { type Component, shallowRef } from 'vue'
import IconSettings from './IconSettings'
import IconHome from './IconHome'

const components = ref<Record<string, Component>>({})

// Later in our code
components.value.settings= IconSettings
components.value.home = IconHome
</script>

We can also use shallowRef for a single component reference.

const settings = shallowRef(IconSettings)

Easy wrapper components with defineModel

I've previously written about how to create an input wrapper in Vue 3 by binding events manually. However, starting from Vue 3.4, there's now a simpler way to achieve this using defineModel.

<template>
  <div>
    <label class="block">
      {{ label }}
    </label>
    <input v-model="model" type="text" class="rounded border p-2" />
  </div>
</template>

<script setup lang="ts">
defineOptions({
  name: 'InputWrapper'
})

withDefaults(defineProps<{ label?: string }>(), {
  label: ''
})

const model = defineModel<string>({ default: '' })
</script>

Working with disabled attribute inheritance

In Vue 3, event listeners, as well as style and class, are now part of all attributes. When we're working with inheritAttrs: false, we often want to distribute different attributes across various parts of our components. In the following examples, we'll see how we can manage this.

Get listeners like in Vue 2

We can still extract event listeners specifically by using useAttrs and a computed property.

<template>
  <div>
    <button type="button" v-bind="listeners">✕</button>
  </div>
</template>

<script setup lang="ts">
import { computed, useAttrs } from 'vue'

defineOptions({
  inheritAttrs: false
})

const allAttrs = useAttrs()

const listeners = computed(() => {
  return Object.keys(allAttrs).reduce((acc, curr) => {
    if (curr.startsWith('on')) {
      return { ...acc, [curr]: allAttrs[curr] }
    } else {
      return acc
    }
  }, {})
})
</script>

Get all attrs without style and classes

Sometimes, it's useful to separate style and classes from the rest of the attributes. We can easily do this by using the spread operator to extract them from all attributes.

import { computed, useAttrs } from 'vue'

const allAttrs = useAttrs()

const attrs = computed(() => {
  const { class: classes, style, ...rest } = allAttrs

  return rest
})

Get only style from attrs

Similarly, we can extract any part we want from all attributes. Here's an example showing how we can extract style.

import { type StyleValue, computed, useAttrs } from 'vue'

const allAttrs = useAttrs()

const style = computed(() => {
  return allAttrs.style as StyleValue
})

That was it!
I hope these snippets and tips help streamline your development process with Vue 3 and TypeScript. If you have your own most-used snippets or find yourself frequently forgetting how to do certain things in Vue, feel free to share them in the comments.

Thanks for reading!

A simple Vue form validation composable with Zod

Giannis Koutsaftakis — Sat, 09 Dec 2023 17:54:43 +0000

The Vue ecosystem is packed with many great form validation libraries, VeeValidate, Vuelidate, and FormKit just to name a few.

Sometimes our use case might not require a full-blown form validation library though and we might already have a schema validation library installed in our project such as Zod or Yup. In that case, a simple Vue composable is all that is needed to provide a great form validation UX.

In this article we'll see how to create a simple Vue composable for form validation with just a few lines of code, that uses Zod under the hood to validate form data.

The idea / how it works

By leveraging Vue's watch method, our composable will track changes in the provided data object (that holds the form's data) and trigger the safeParseAsync method from Zod to perform real-time validation. It's worth noting that for big nested objects, there might be a potential performance consideration. However, most of the time, typical forms in a web app contain a limited number of fields, so unless you are validating a huge object, that shouldn't pose an issue. Additionally, the exceptional performance of Vue 3, coupled with robust support for JavaScript proxies in modern browsers, ensures that our composable will be efficient and responsive in the vast majority of practical use cases.

Validation modes

There are many school of thoughts regarding the optimal UX in form validation. Our composable will support two validation modes: one for lazy (or after-submit) and one for eager validation, offering a versatile solution that will enable us to select the approach that aligns best with the desired user experience.

Lazy
Lazy (or after-submit) validation, allows users to fill out the entire form before triggering the validation process. Upon hitting the submit button (i.e. calling the validate method), the composable will validate the information and return the error messages (if they exist). From that point onwards the composable will report any errors found in realtime.

Eager
In eager validation, messages are displayed as soon as the users start typing (before even hitting the submit button), encouraging them to take immediate corrective action.

While both methods have their merits, I prefer lazy validation from a UX perspective. By deferring error messages until the form completion stage, we minimize interruptions during data entry, contributing to a smoother, less distracting user experience and reducing potential frustration.

With that out of the way, let's get to the code itself!

useValidation.ts

// Import necessary libraries
import { type ZodTypeAny, z } from 'zod'
// We use `get` and `groupBy` from `lodash` for brevity
import { get, groupBy } from 'lodash-es'
import { ref, watch, toValue, type MaybeRefOrGetter } from 'vue'

export default function <
  T extends ZodTypeAny,
  U = Record<string, unknown>,
  V = Record<string, z.ZodIssue[]>
>(schema: MaybeRefOrGetter<T>, data: MaybeRefOrGetter<U>, options?: { mode: 'eager' | 'lazy' }) {
  // Merge default options with user-defined options
  const opts = Object.assign({}, { mode: 'lazy' }, options)

  // Reactive variables to track form validity and errors
  const isValid = ref(true)
  const errors = ref<V | null>(null)

  // Function to clear errors
  const clearErrors = () => {
    errors.value = null
  }

  // Function to initiate validation watch
  let unwatch: null | (() => void) = null
  const validationWatch = () => {
    if (unwatch !== null) {
      return
    }

    // Watch both data and schema for changes
    unwatch = watch(
      [() => toValue(data), () => toValue(schema)],
      async () => {
        await validate()
      },
      { deep: true }
    )
  }

  // Function to perform validation
  const validate = async () => {
    clearErrors()

    // Validate the form data using Zod schema
    const result = await toValue(schema).safeParseAsync(toValue(data));

    // Update validity and errors based on validation result
    isValid.value = result.success

    if (!result.success) {
      errors.value = groupBy(result.error.issues, 'path')
      validationWatch()
    }

    return errors
  }

  // Function to scroll to the first error in the form
  const scrolltoError = (selector = '.is-error', options = { offset: 0 }) => {
    const element = document.querySelector(selector)

    if (element) {
      const topOffset = element.getBoundingClientRect().top - document.body.getBoundingClientRect().top - options.offset

      window.scrollTo({
        behavior: 'smooth',
        top: topOffset
      })
    }
  }

  // Function to get the error message for a specific form field, can be used to get errors for nested objects using dot notation path.
  const getError = (path: string) => get(errors.value, `${path.replaceAll('.', ',')}.0.message`)

  // Activate validation watch based on the chosen mode
  if (opts.mode === 'eager') {
    validationWatch()
  }

  // Expose functions and variables for external use
  return { validate, errors, isValid, clearErrors, getError, scrolltoError }
}

How to use

The composable takes a Zod object schema (can be a reactive variable) and a data object that holds the form data that we want to validate (can be either reactive or ref) as parameters and returns refs and functions that we can then use in our component. Optionally it can also accept an options object to set the validation mode.

If you want to use a dynamic schema, it's best to define the schema as a shallowRef for performance reasons.

const { validate, errors, isValid, clearErrors, getError, scrolltoError } = useValidation(validationSchema, form, {
  mode: 'lazy',
});

validate - An async function that triggers the validation process based on the provided Zod schema and the current form data. It returns the validation errors if any, or null if the validation is successful.
errors - A ref that holds the validation errors in the form of a grouped object, where each property corresponds to a form field path (e.g. address.city), and its value is an array of Zod validation issues.
isValid - A boolean ref that tracks the overall validity of the form.
clearErrors - A function that clears the current validation errors, setting the errors ref to null. Useful when you want to reset the form errors before triggering a re-validation.
getError - A helper function to retrieve the error message for a specific form field path. It takes a keypath with dot notation as an argument and returns the first error message for that field.
scrolltoError - A function that scrolls the page to the first form field with an error, making it visible to the user. It takes optional parameters for the error selector and scroll options.

Using these returns we can handle form validation, retrieve error details, and manage the user interface based on the validation status, contributing to a robust and user-friendly form validation experience!

Live example

Here is a Stackblitz showcasing the useValidation composable in action https://stackblitz.com/edit/vue-use-validation-composable-97kjhtnd?file=src%2FuseValidation.ts.
The form is using components from PrimeVue and includes fields for a user's profile information, featuring nested address details.

That was it!
It's amazing how much functionality you can cram into a small composable using Vue's reactivity primitives! Feel free to experiment with the code, and change it to make it work for your use case.

Thanks for reading!

Extend Vue Test Utils - findByText

Giannis Koutsaftakis — Sat, 10 Jun 2023 11:33:55 +0000

When it comes to testing Vue components, Vue Test Utils is the official testing library that provides a rich set of utilities for interacting with and asserting on components in a Vue application. However, just like any library, there are always opportunities for enhancements and additions to further improve the testing experience.

If you've used other testing libraries like testing-library, Cypress etc, one pattern that you might have found useful is to select elements based on their text content (e.g getByText, cy.contains etc).
Although Vue Test Utils supports finding elements using CSS selectors via the find and findAll methods, it doesn't provide a method for getting elements by text.

Thankfully, Vue Test Utils includes a Plugin API that lets us extend its capabilities with custom logic, methods, or functionality, so we can create our own findByText method 🎉.

Let's get right to it then!

Create and register the extends file

Create a file for your Vue Test Utils extends, e.g. vue-test-utils.extends.js and save it to your preffered location.

You'll need to register that file in your test runner's configuration so that it runs before each test.

For Jest, that would be inside jest.config.js setupFilesAfterEnv array

jest.config.js

module.exports = {
  ...
  setupFilesAfterEnv: ['./tests/jest.extends.js'],
}

For Vitest that would be inside vite.config.js test setupFiles

vite.config.js

/// <reference types="vitest" />
import { defineConfig } from 'vite'

export default defineConfig({
  ...
  test: {
    ...
    setupFiles: './tests/jest.extends.js',
  },
});

With that out of the way it's time to add our findByText function.

`findByText` function

jest.extends.js

import { config, createWrapperError } from '@vue/test-utils';

const Plugin = (wrapper) => {
  function findByText(str, selector = '*') {
    const items = wrapper.findAll(selector);

    for (let i = 0; i < items.length; i++) {
      const item = items[i];

      if (item.text().trim() === str.trim()) {
        return item;
      }
    }

    return createWrapperError('DOMWrapper');
  }

  return {
    findByText,
  };
};

config.plugins.VueWrapper.install(Plugin);

Details

The findByText function uses the findAll method of Vue Test Utils under the hood in order to find elements and then loops over them to find the text that matches the string passed as an argument. Optionally, we can also pass a selector as a second argument if we want to narrow down the results to a specific container.

Things to note:
The function performs a case-sensitive text match so ensure that the text parameter exactly matches the casing of the desired text content. It also trims both the text and the actual text content of the elements being searched to remove leading and trailing whitespace, allowing for more flexible matching.

Feel free to change the code that does the matching part to your own liking.

Parameters

text (string): The text content to search for within the component's wrapper.
selector (string): (Optional) CSS selector used to narrow down the search scope. Defaults to '*', which matches all elements within the wrapper.

Return Value

element (DOMWrapper): A DOMWrapper object representing the first element that matches the given text within the wrapper. If no matching element is found, an error is thrown.

Example

import { mount } from '@vue/test-utils';

const Component = {
  template: `
    <div>
      <span class="test1">Foo</span>
      <span class="test2">Bar</span>
    </div>
  `,
};

const wrapper = mount(Component);

const span = wrapper.findByText('Foo');

expect(span.classes()).toContain('test1');

Final notes

We saw how you can use Vue Test Utils Plugin API to extend its functionality. Using the same format we can create other query functions to use in our tests without the need to install another 3rd party testing library.

Happy component testing!

Skeleton Loader using Vue & Tailwind

Giannis Koutsaftakis — Fri, 06 Jan 2023 15:42:28 +0000

A skeleton loader (otherwise known as skeleton screen, content loader, ghost element, and content placeholder) is a great way to improve our app's user experience. Using it instead of a loading spinner, for showing that content is loading, makes the user feel like the application is more responsive and faster.

The issue with skeleton loaders though is that they need to have a different design depending on the place that they are used, thus making them more difficult to implement.

Tailwind to the rescue

Let's see how we can create a skeleton loader component that includes an animated "shimmer" effect, using Tailwind and Vue.js. It will serve as the building block for creating skeleton content placeholders for all kinds of sections.

So, rather than creating a separate skeleton component for each element or section (e.g texts, headings, images, videos etc), the concept is to utilize Tailwind classes to shape multiple skeleton loader instances exactly how we want them and combine them in order to create the desired result!

Skeleton loader component

Our component will be as simple as possible using one div for the skeleton and one div for the shimmer. We'll need some props in order to set the skeleton type (rectangle or circle) and skeleton colors as well.

SkeletonLoader.vue

<template>
  <div :class="[bgClass, loaderClass, 'relative overflow-hidden']">
    <div class="shimmer absolute top-0 right-0 bottom-0 left-0" :style="shimmerStyle"></div>
    <slot />
  </div>
</template>

<script lang="ts">
const LOADER_TYPES = { rectangle: 'rectangle', circle: 'circle' };

const LOADER_CSS_CLASSES = {
  [LOADER_TYPES.rectangle]: 'rounded',
  [LOADER_TYPES.circle]: 'rounded-full',
};

type LoaderTypesKeys = keyof typeof LOADER_TYPES;
type LoaderTypesValues = typeof LOADER_TYPES[LoaderTypesKeys];

const SHIMMER_COLOR = '#ffffff';

const isHexColor = (hexColor: string) => {
  const hex = hexColor.replace('#', '');

  return typeof hexColor === 'string' && hexColor.startsWith('#') && hex.length === 6 && !isNaN(Number('0x' + hex));
};

const hexToRgb = (hex: string) => `${hex.match(/\w\w/g)?.map((x) => +`0x${x}`)}`;
</script>

<script setup lang="ts">
import { computed, toRefs } from 'vue';

const props = defineProps({
  type: {
    type: String,
    default: LOADER_TYPES.rectangle,
    validator(value: LoaderTypesValues) {
      return Object.values(LOADER_TYPES).includes(value);
    },
  },
  bgClass: {
    type: String,
    default: 'bg-gray-300',
  },
  cssClass: {
    type: String,
    default: '',
  },
  shimmerColor: {
    type: String,
    default: SHIMMER_COLOR,
  },
});

const { type, bgClass, cssClass, shimmerColor } = toRefs(props);

const shimmerStyle = computed(() => {
  const rgb = isHexColor(shimmerColor.value) ? hexToRgb(shimmerColor.value) : SHIMMER_COLOR;

  return {
    backgroundImage: `linear-gradient(90deg, rgba(${rgb}, 0) 0%, rgba(${rgb}, 0.2) 20%, rgba(${rgb}, 0.5) 60%, rgba(${rgb}, 0))`,
  };
});

const loaderClass = computed(() => (cssClass.value ? cssClass.value : LOADER_CSS_CLASSES[type.value]));
</script>

<style lang="css" scoped>
.shimmer {
  transform: translateX(-100%);
  animation: shimmer 1.4s infinite;
}

@keyframes shimmer {
  100% {
    transform: translateX(100%);
  }
}
</style>

Customization with `props` and `slot`

Props

type sets the type of the skeleton loader to rectangle (default) or circle.
bgClass used to explicitly set the class for the background color of the skeleton loader. Usually that would be a bg- variant Tailwind class.
cssClass used to set custom CSS classes for the skeleton loader. In case this prop is used, the loader won't have any classes set by default (apart from the background class).
shimmerColor used to set the shimmer color, expects a hex color string. If no valid hex string will be provided, the shimmer will fallback to the default (white) color.

I'm sure you noticed that there are no width and height props. Although we could easily add those, we will instead utilize Vue's fallthrough attributes feature to set the desired width/height using either Tailwind classes or simply by using style.

There are other props that we could have included in our component as well, like props to set the shimmer animation duration or the shimmer CSS class etc. We'll leave these out in order to keep the code size in this example as compact as possible, feel free to experiment by adding any props you find useful.

Slot

Our component includes a default slot that we can use to customize the contents of our skeleton loader div. Useful in case we want our skeleton not to be just an empty div but also to contain an image, a text or even another component etc.

How to use

Alright, we have our base skeleton loader component ready, it's time to use it to create some skeleton loader placeholders!

Text of various sizes

<SkeletonLoader class="w-16 h-5" />
<SkeletonLoader class="w-32 h-4 mt-4" />
<SkeletonLoader class="w-72 h-2.5 mt-2" />
<SkeletonLoader class="w-52 h-4 mt-6" />
<SkeletonLoader class="w-72 h-2.5 mt-2" />
<SkeletonLoader class="w-72 h-2 mt-2" />

Notice how we're using Tailwind classes to set the width and height.

Card

<div class="p-4 max-w-sm rounded border border-gray-200 md:p-6">
  <SkeletonLoader class="mb-4 h-48 flex justify-center items-center text-gray-400"> Image </SkeletonLoader>
  <SkeletonLoader class="h-2.5 w-48 mb-4" />
  <SkeletonLoader class="h-2 mb-2.5" />
  <SkeletonLoader class="h-2 mb-2.5" />
  <SkeletonLoader class="h-2" />
  <div class="flex items-center mt-4 space-x-3">
    <SkeletonLoader type="circle" class="w-14 h-14 flex justify-center items-center text-gray-400"> Icon </SkeletonLoader>
    <div>
      <SkeletonLoader class="h-2.5 w-32 mb-2"></SkeletonLoader>
      <SkeletonLoader class="w-48 h-2" />
    </div>
  </div>
</div>

This is a more complete example that utilizes the slot and also the rectangle and circle types of the loader to create a skeleton card.

Demo with examples

Checkout more examples and the full code in the Stackblitz example here: https://stackblitz.com/edit/vue3-tailwind-vbdfja?file=src/App.vue

Thanks for reading!

A Vue dropdown menu with Floating Vue & Tailwind

Giannis Koutsaftakis — Sun, 28 Aug 2022 20:40:23 +0000

One of the most popular libraries available for creating tooltips, popovers and menus in Vue applications is floating-vue. Although floating-vue provides a Dropdown component, styling it and adding additional functionality, like e.g keyboard navigation, is left up to the user.

What we'll create

We'll use the Dropdown component of floating-vue as a base and then add keyboard functionality on top. We'll then use that component to create a dropdown menu using Tailwind.

The end result will resemble Bootstrap's Dropdown component.

Let's get to it then!

Dropdown component

Luckily Vue.js allows us to easily extend any component using the "wrapper component" technique. So our final component will include all functionality of floating-vue Dropdown plus:

Capability to move through individual dropdown items using the cursor up/down keys
Customizable CSS selector for the dropdown items used for the keyboard navigation
Open and close the dropdown with the Space and Enter keys when the dropdown trigger has focus
Prevent page scroll while navigating the menu with the keyboard
Close the dropdown by clicking outside or by using the Esc key

Dropdown.vue

<template>
  <FloatingVueDropdown ref="popoverRef" :distance="14" :triggers="['click']" theme="dropdown-menu" placement="bottom-start" auto-hide @show="onShow" @hide="onHide">
    <template v-for="(_, slot) in $slots" #[slot]="scope">
      <slot :name="slot" v-bind="scope || {}" />
    </template>
  </FloatingVueDropdown>
</template>

<script setup>
import { Dropdown as FloatingVueDropdown } from 'floating-vue';
import { onBeforeUnmount, ref } from 'vue';

const popoverRef = ref(null);

const props = defineProps({
  itemSelector: {
    type: String,
    default: 'li > a:not(:disabled)',
  },
});

const popoverKeydown = (e) => {
  const popover = popoverRef.value;

  if (!popover) {
    return;
  }

  if (['ArrowUp', 'ArrowDown'].includes(e.key)) {
    e.preventDefault();

    const items = [...popover.$refs.popperContent.$el.querySelectorAll(props.itemSelector)];

    if (!items.length) {
      return;
    }

    let index = items.indexOf(e.target);
    index = e.key === 'ArrowDown' ? index + 1 : index - 1;
    items[index]?.focus();
  }

  if ((e.key === 'Enter' || e.key === ' ') && e.target === popover.$refs.popperContent.$el) {
    e.preventDefault();
    popover.hide();
  }
};

const onShow = () => {
  document.addEventListener('keydown', popoverKeydown);
};

const onHide = () => {
  document.removeEventListener('keydown', popoverKeydown);
  const popover = popoverRef.value;
  popover?.$refs.popper.$_targetNodes[0].focus();
};

onBeforeUnmount(() => {
  document.removeEventListener('keydown', popoverKeydown);
});
</script>

<style>
.v-popper--theme-dropdown-menu .v-popper__arrow-container {
  display: none;
}
</style>

Breakdown of the most important parts

Pass down slots to the floating-vue Dropdown component.

<FloatingVueDropdown>
  <template v-for="(_, slot) in $slots" #[slot]="scope">
    <slot :name="slot" v-bind="scope || {}" />
  </template>
</FloatingVueDropdown>

Set some component defaults
- ref="popoverRef" - The popover ref, we need it for our DOM related operations.
- :distance="14" - Set the distance between the dropdown trigger and the dropdown menu
- :triggers="['click']" - Open the dropdown on click
- theme="dropdown-menu" - Set the a theme to our own theme, essentially removing all the default floating-vue Dropdown styles.
- placement="bottom-start" - Default placement of the dropdown
- auto-hide @show="onShow" - Method that runs when the Dropdown gets shown
- @hide="onHide" - Method that runs when the Dropdown gets hidden
The itemSelector prop - This is the selector that the component will use internally to get the dropdown items that keyboard navigation will cycle through.
The popoverKeydown method - This method, that gets registered as a document keydown listener when the dropdown gets shown (in onShow method), includes all the keyboard functionality. We' re listening for up/down arrows key-presses and we cycle through an Array of dropdown items setting focus on an item depending on the direction. We also listen for Enter and Space key-presses so when these take place on the dropdown trigger, we open the dropdown. Notice the usage of e.preventDefault();, this is so that the page doesn't scroll while using up/down keys when the dropdown is open.
The onHide method removes the document keydown listener and returns focus to the dropdown trigger.

Structure and Styling

We have our base Dropdown component ready, let's use it to create a dropdown menu using Tailwind!

App.vue

<template>
  <Dropdown class="inline" popper-class="w-64 bg-white border rounded-lg shadow-md">
    <!-- Dropdown trigger -->
    <button
      class="inline-block px-6 py-3 bg-blue-600 text-white leading-tight rounded hover:bg-blue-700 focus:bg-blue-700 focus:outline-none focus:ring-0 active:bg-blue-800 transition duration-150 ease-in-out"
    >
      Dropdown button
    </button>

    <!-- Dropdown content -->
    <template #popper="{ hide }">
      <ul class="py-1 text-gray-70">
        <li>
          <a href="#" class="block py-2 px-4 hover:bg-gray-100 focus:bg-gray-100 outline-none" @click="hide">
            Click me to close
          </a>
        </li>
        <li>
          <a href="#" class="block py-2 px-4 hover:bg-gray-100 focus:bg-gray-100 outline-none">Menu item</a>
        </li>
        <li>
          <a href="#" class="block py-2 px-4 hover:bg-gray-100 focus:bg-gray-100 outline-none">Another menu item</a>
        </li>
      </ul>
    </template>
  </Dropdown>
</template>

<script setup>
import Dropdown from './Dropdown.vue'
</script>

That's it!

Here is a live example of the end result in this Stackblitz here.

You might also want to check out vue-simple-dropdown, a dropdown component for floating-vue ready to be imported into your Vue project!

Manual form input bindings in Vue.js

Giannis Koutsaftakis — Wed, 04 May 2022 22:33:53 +0000

When creating forms with Vue.js most of the times we' re using v-model for our form input bindings. v-model makes it super easy to sync the data model with our form fields' values and vice versa.

It's the so called two-way binding.

There can be times though that we need more control on the field's value binding and this is when manual binding comes in.

v-model under the hood

Vue.js documentation gives us a hint on how v-model works under the hood. It wire's up value bindings and change event listeners to the field element that is used on.

For example an <input v-model="text"> translates to

<input
  :value="text"
  @input="event => text = event.target.value"
>

Here are the different DOM properties and event pairs for the basic form elements that we can leverage in order to recreate the v-model two-way binding manually using v-bind (:) and v-on ( @):

Element	Property	Event
input	:value	@input
textarea	:value	@input
checkbox	:checked	@change
radio	:checked	@change
select	:value	@change

Let's check how that looks in actual code

Manual binding examples

Although an example for two-way form input bindings using v-model exists in the Vue.js docs site, there's no example on how to create the same bindings manually.

Let's see how we can create manual bindings for checkbox and radio as these are the most tricky to get right.

At the end of this article you will find a CodeSandbox that recreates the Vue.js Form Bindings example using manual bindings. It also includes examples for manual binding multi-checkbox and multi-select lists.

Checkbox

We usually bind a checkbox to a boolean value in our data model. Here's how to do that using manual binding.

<input
  type="checkbox"
  :checked="booleanValue"
  @change="booleanValue = $event.target.checked"
/>

The key here is to v-bind the checked property and then assign the value back to the data model by reading the checkbox's checked attribute when the change event is fired.

$event is a special variable that gives us access to the original DOM event inside the inline handler.

Radio

When binding radio buttons we'll most likely use a text variable to hold the selected value. Manual binding works like this: We bind the checked property to the result of an expression that evaluates to whether the current selected value corresponds to that specific radio button. We read the selected value of the radio using the change event.

Notice that we use $event.target.value as we need the actual text value.

<input
  type="radio"
  value="One"
  :checked="textValue === 'One'"
  @change="textValue = $event.target.value"
/>

<input
  type="radio"
  value="Two"
  :checked="textValue === 'Two'"
  @change="textValue = $event.target.value"
/>

More examples...

You can check the CodeSandbox here for detailed examples that also demonstrate how to bind multi-checkbox and multi-select lists.

It's good to know that manual binding works in exactly the same way in both Vue.js 2 and Vue.js 3.

Thanks for reading!

Using Axios in Nuxt with Composition API

Giannis Koutsaftakis — Sat, 12 Mar 2022 21:37:59 +0000

A common pattern when using Axios in Vue.js apps, is to create a custom axios instance with interceptors attached in order to handle things (like e.g authentication and error reporting) globally.
We then use that instance in our API functions that are grouped inside files and/or folders depending on the business context.
Finally we import the API functions inside our components in order to fetch data.

Let's look at how we can implement the same pattern in Nuxt when using the composition api.

Install Nuxt composition API

Since we'll be using the Vue.js composition API we'll install the Nuxt plugin that will allow us to use the Vue 3 Composition API with Nuxt-specific features.

npm install @nuxtjs/composition-api

Let's add it in nuxt.config.js inside the buildModules array.

nuxt.config.js

{
  ...
  buildModules: [
    '@nuxtjs/composition-api/module'
  ]
  ...
}

Install, setup, and configure Nuxt Axios

We also need the nuxt/axios plugin which integrates Axios to Nuxt. There's no need to install axios as a standalone package, as the plugin takes care of that under the hood.

npm install @nuxtjs/axios

We'll add it in nuxt.config.js inside the modules array.

We're also using the axios key in order to set some global options which will be applied to all requests. In this case we're only adding our API base URL as an example.

nuxt.config.js

{
  ...
  modules: [
    '@nuxtjs/axios'
  ],
  axios: {
    baseURL: 'https://reqres.in/api/',
  }
  ...
}

Create and customize the Axios instance

In order to customize Axios by registering interceptors and changing global config, we have to create and register a Nuxt plugin. We are injecting our instance as api into the context so that we can use it later in our functions as $api using the useContext composable.

plugins/api.js

export default function ({ $axios, app }, inject) {
  const api = $axios.create()

  api.onRequest((config) => {
    console.log(`Making request to ${config.url}`)
  })

  api.onError((error) => {
    const code = parseInt(error.response && error.response.status)
    const errorText = code
      ? `A request failed with status code ${code}`
      : `A network error occurred`

    console.error(errorText)
  })

  api.onResponse((res) => {
    return res.data
  })

  inject('api', api)
}

We can use the onRequest, onResponse, and onError helpers to intercept the request/response and handle errors respectively. Learn more about nuxt/axios helpers here. In our example we'll just use the onResponse helper to return the data from the response instead of the whole response object.

We are now ready to create our API functions and use them inside our Vue.js components

API functions

We are using the reqres API in our example to setup two methods for fetching users.

Notice how we're implementing our module as a composable so that it exports a function that returns an object with our data-fetching methods. We need to do this because useContext only works inside the Vue component's setup method.

api/user.js

import { useContext } from '@nuxtjs/composition-api'

export const userApi = () => {
  const { $api } = useContext()

  const fetchUser = async (userId) => {
    const res = await $api.get(`users/${userId}`)

    return res
  }

  const fetchUsers = async () => {
    const res = await $api.get('users')

    return res
  }

  return {
    fetchUser,
    fetchUsers,
  }
}

finally we can

Use the API functions inside our components

We can call our API function directly or use useFetch or useAsync depending on what we want to achieve.

<template>
  <div>
    <div>
      <button type="button" class="btn btn-primary" @click="loadUsers">
        Fetch users
      </button>
    </div>
    <div>
      <pre>{{ users }}</pre>
    </div>
  </div>
</template>

<script>
import { defineComponent, ref } from '@nuxtjs/composition-api'
import { userApi } from '@/api/user'

export default defineComponent({
  setup() {
    const { fetchUsers } = userApi()
    const users = ref([])

    const loadUsers = async () => {
      const res = await fetchUsers()
      users.value = res.data
    }

    return {
      users,
      loadUsers,
    }
  },
})
</script>

That was it, using this technique we can group our API calls in functions as we would do in a plain Vue.js app.

Here's a StackBlitz example that demonstrates it in action.

Thanks for reading!

Create a nice search bar UX with vue-search-input

Giannis Koutsaftakis — Sun, 30 Jan 2022 20:21:46 +0000

The page search input, also named search box, search bar, quick search, quick find etc, is an integral part of any website or web app. Usually positioned at the top of the page (either left, center or right) the search bar is often the first interaction a user has with a website, as it provides a quick way to find information.

UX (best) practices

There are a lot of good write-ups such as this one by Dawson Beggs posted at UX Collective, regarding how a good search bar UX must be. Every website/web-app implements the global search input differently though. Let's take a quick look at how some of the popular ones are handling it.

Storybook

Storybook is a widely used, open source tool for building UI components in isolation.

Magnifier icon on the left side
Clear icon x
Pressing the esc does not blur the input, but clears the input's text
It includes a focus icon \ which disappears on input focus
The \ key moves focus to the input also selecting the text inside it

GitHub

GitHub is used by over 73 million developers to host their Git repositories.

No magnifier icon on the left or the right side
No clear icon x
The esc key blurs the input, but does not clear the input's text
It includes a focus icon \ which disappears on input focus
The \ key moves focus to the input without selecting the text

Gmail

Gmail is probably the most popular free email service.

Magnifier icon on the left side
Clear icon x
Search options icon on the right side of the input
The esc key blurs the input but does not clear the input's text
There's no focus icon \
The \ key doesn't move focus to the input

Your website, depending on the UX that you are trying to achieve, might require a different combination of these features.

Have no fear though, if you are using Vue.js 3 as your frontend framework (and you should 😉), vue-search-input has got you covered.

vue-search-input

vue-search-input is a Vue.js 3 search input component, inspired by the global search input of Storybook and GitHub. Although headless by default, it includes a sample stylesheet as well as all of the necessary features so that you can create the perfect search bar experience for your use-case.

Features at a glance

Focus on the search input at any time by pressing the / key on the keyboard.
Includes a default CSS styling but it's also easy to bring your own styles too.
Displays an x icon on the right side of the search input, used for clearing the text when there's a value typed inside.
The search text gets cleared by pressing the esc key when the search input has focus (configurable).
Completely customizable behavior via props.
Customizable icons via slots.

Installation and Usage

Install with npm

npm i vue-search-input

Import it in your app

import SearchInput from 'vue-search-input'

Optionally import styles

import 'vue-search-input/dist/styles.css'

Use it inside the template with a bound reactive variable

<SearchInput v-model="searchVal" />

Customization with `props` and `slots`

Props

You can customize the behavior and turn features on/off using props.

Name	Type	Default	Description
type	string	`search`	The type of the input field. Allowed types are `search` and `text`
modelValue (v-model)	string	The input's value	`''`
wrapperClass	string	The default CSS class of the wrapper div	`search-input-wrapper`
searchIcon	boolean	Displays the "search" icon	true
shortcutIcon	boolean	Displays the "shortcut" icon	true
clearIcon	boolean	Displays the "clear text" icon	true
hideShortcutIconOnBlur	boolean	Whether to hide the shortcut icon when the input loses focus	true
clearOnEsc	boolean	Whether to clear the input field when the `esc` key is pressed	true
blurOnEsc	boolean	Whether to takes the focus out of the input field when the `esc` key is pressed	true
selectOnFocus	boolean	Selects the input's text upon `/` keypress	true
shortcutListenerEnabled	boolean	Enables the functionality for the `/` keypress	true
shortcutKey	string	The `key` for the shortcut functionality	`/`

Slots

vue-search-input includes some default icons but you can also customize them to suit your needs using the available slots.

Name	Description	Default content
search-icon	Slot for the search icon	`<i class="search-icon search"></i>`
shortcut-icon	Slot for the shortcut icon	`<i class="search-icon shortcut" title='Press "/" to search'></i>`
clear-icon	Slot for the clear icon `{ clear: () => void }` the function that clears the input	`<button class="search-icon clear" aria-label="Clear" @mousedown="clear" @keydown.space.enter="clear"></button>`
append	Adds an item inside the input wrapper, before the search icon	-
append-inner	Adds an item inside the input wrapper, after the search icon	-
prepend	Adds an item inside the input wrapper directly after the input element	-
prepend-outer	Adds an item inside the input wrapper directly after the clear icon	-

Demo with examples

Checkout an online demo of vue-search-input which includes examples that mimic the search bar functionality of Storybook, GitHub, Gmail and YouTube!
https://vue-search-input.vercel.app

If you liked vue-search-input it would be awesome if you visit its repo on GitHub and give it a star.

Thanks for reading!

How to handle loading progress flicker

Giannis Koutsaftakis — Wed, 29 Dec 2021 07:37:48 +0000

One of the most important things in our web apps UX is to provide a form of feedback when the app needs more time to process the user's action when e.g an ajax request is fired in the background. This is usually done using a progress bar, a spinner, or a combination of both.

Have you ever noticed though a "flaky" behavior when a lot of API calls happen at the same time?

We can provide a smooth experience to our users, so let's fix that!

What we'll build

We'll create a simple loader handler function for Promises that will make sure our loading indicator will disappear only when the last unresolved Promise gets resolved. We'll also make sure that the function is reusable so that it can be used with any project and with any progress loading indicator plugin.

Implementation

createLoader.ts

export const createLoader = (options: {
  start: () => void;
  end: () => void;
  inc?: () => void;
  slackTime?: number;
}) => {
  const promises: Promise<unknown>[] = [];

  const opts = {
    ...{
      inc: () => {},
      slackTime: 0,
    },
    ...options,
  };

  const load = <T>(promise: Promise<T> | (() => Promise<T>)) => {
    const p = typeof promise === 'function' ? promise() : promise;

    !promises.length && opts.start();
    promises.push(p);

    p.finally(() => {
      setTimeout(() => {
        promises.pop();
        !promises.length ? opts.end() : opts.inc();
      }, opts.slackTime);
    });

    return p;
  };

  return { load };
};

We created a factory function that takes an options object as a parameter. The options object defines which operations will be performed on loading start/end and optionally an operation to execute when a Promise is resolved.

We can also define a slackTime that will be used as a delay to wait until the last Promise is resolved. This is useful in cases that we have e.g an API call that starts shortly after another call has just finished, causing a "flickering" effect in our loader.

The factory function will return our load method which will accept a Promise or a function that returns a Promise. Instead of firing our async functions directly, we'll pass them through our load function instead. Our loader then will make sure that the loading progress ends when the last of the Promises is resolved.

Options

Option	Description	Type	Default
`start`	A function to execute on loading start, this is where we start our progress loader	`function`	`undefined`
`end`	A function to execute when loading ends, this is where we stop our progress loader	`function`	`undefined`
`inc`	An optional function to execute when a promise resolves (valid for all promises except the last one). We can use this function to increment our loading progress.	`function`	`() => {}`
`slackTime`	Time in `ms` to wait until last promise is resolved as to enable multiple operations in a sequence without re-triggering a loader progress start	`Number`	`0`

Creating our loader

It's time to create our loader. Here we're using the popular nprogress library for our progress loading indicator as an example.

loader.ts

import NProgress from 'nprogress';
import { createLoader } from './createLoader';

NProgress.configure({
  minimum: 0.35,
  speed: 300,
});

const start = () => {
  NProgress.start();
};

const end = () => {
  NProgress.done();
};

const inc = () => {
  NProgress.inc(0.05);
};

const loader = createLoader({ start, end, slackTime: 350, inc });

export const { load } = loader;

We have configured the NProgress instance and setup a new loader that will start, end, or increment the nprogress progress bar depending on the Promises' state.

How to use

Using our loader is fairly simple, we just need to pass our Promises into the load function and our loader will take care of the rest. Here's an example using axios that dispatches two requests so that they get registered in our loader.

import { load } from './loader';
import axios from 'axios';

const res1 = load(axios.get(`https://jsonplaceholder.typicode.com/todos`));
const res2 = load(axios.get(`https://jsonplaceholder.typicode.com/todos/1`));

That's it, no more loading progress flicker!

If you want to see how this feels in a browser, checkout a live example of the loader that implements a global page progress bar (and some extra stuff too) in this stackblitz here

Make sure you open this with a Chromium-based browser (e.g Chrome) and run npm run dev on the console.

Update:
promise-loading-handler is now an npm package. You can include it in your JS project with npm install promise-loading-handler

Thanks for reading.

Getting started with Playwright E2E testing

Giannis Koutsaftakis — Tue, 05 Oct 2021 20:22:58 +0000

Playwright is a cross-browser web automation framework by Microsoft. It is also a powerful E2E testing tool with its integrated test runner Playwright Test.

Some of the highlight features of Playwright:

Support for 3 browser engines (Chromium, Firefox and WebKit)
Write tests in JavaScript & TypeScript, Python, .NET and, Java
Runs tests in parallel using worker processes that run at the same time
Support for screenshots and videos snapshots taking
Provides a great set of debugging tools
Wide range of element selectors (CSS, text, X-path and more)
Intercept network activity for stubbing and mocking network requests (e.g API calls)
CLI tool to Record user interactions and generate JavaScript code

more...

In this post we' re going to implement two simple E2E test flows for pages that require authentication and look at how we can reuse the login state so that we don't have to repeat the same code across our tests.

We're going to use JavaScript as our language of choice and the beautiful Vuexy admin theme as an example domain for testing.

Let's start!

Install dependencies

Playwright and friends

# install playwright and its test runner
npm i -D @playwright/test

# install browser engines - Chromium, Firefox, and Webkit
npx playwright install

We're also going to need the dotenv package in order to load the login credentials as environment variables from a .env file into our test.

npm i -D dotenv

Let's add some useful commands into the scripts section of our project's package.json

...
"scripts": {
    "test": "npx playwright test",
    "test-debug": "PWDEBUG=1 npx playwright test",
    "test-debug-windows": "set PWDEBUG=1 && npx playwright test"
},
...

test runs the tests
test-debug runs the tests in debug mode
test-debug-windows runs the tests in debug mode on Windows

Configure

Playwright uses a global configuration file to specify common settings for each test.
Create playwright.config.js in your project's root with the contents below

module.exports = {
  globalSetup: require.resolve('./tests/global-setup.js'),
  use: {
    baseURL: 'https://pixinvent.com',
    headless: true,
    viewport: { width: 1280, height: 720 },
    ignoreHTTPSErrors: true,
    screenshot: 'only-on-failure',
    timeout: 30000,
  }
};

These are some commonly used options for various scenarios.

baseURL Define a common Base URL, this allows us to navigate by using just the path inside our tests. In our example we set it as https://pixinvent.com
globalSetup This file will be required and run before all the tests. We'll use it to setup our login step before every test.
headless Playwright runs tests in headless mode by default, change this to false if you want to view the tests in a "live" browser instance.
viewport Controls the size of the viewport for the tests.
ignoreHTTPSErrors Whether to ignore HTTPS errors during navigation.
screenshot Have a screenshot taken when a test fails.
timeout Time in milliseconds given to each test.

Create a .env file in the project's root that will hold our login credentials.

LOGIN_USERNAME=admin@demo.com
LOGIN_PASSWORD=admin

We'll also need to insert the .env and tests/state.json files to our project's .gitignore file. The tests/state.json will be used to store the authentication state when our tests run, so we don't want that file to be tracked by Git.

.gitignore

# env file
.env

# Login state file
tests/state.json

Create the tests

The tests directory will contain our tests and the globalSetup file.

tests/globalSetup.js

const config = require('../playwright.config');
const { chromium } = require('@playwright/test');
require('dotenv').config();

module.exports = async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto(config.use.baseURL + '/demo/vuexy-vuejs-laravel-admin-template/demo-1/login');

  await page.fill('input[type="text"]', process.env.LOGIN_USERNAME);
  await page.fill('input[type="password"]', process.env.LOGIN_PASSWORD);
  await page.click('button:has-text("Sign in")');

  await page.context().storageState({ path: 'tests/state.json' });
  await browser.close();  
};

Playwright uses the globalSetup.js file to set things up once, before running all tests. In our example we're using it to visit the login page, fill-in the username and password, click on the "Sign in" button and finally, save the authentication state to a state.json file that is going to be used from inside our tests.

Let's add some sample tests

Playwright Test uses the expect library for test assertions, if you have used Jest you will find the syntax familiar.

tests/dashboard.spec.js

const { test, expect } = require('@playwright/test');

test.use({ storageState: 'tests/state.json' });

test('dashboard', async ({ page }) => {
  await page.goto('/demo/vuexy-vuejs-laravel-admin-template/demo-1/dashboard/ecommerce');
  const title = await page.locator('.card.card-congratulation-medal p.card-text.font-small-3');
  await expect(title).toContainText('You have won gold medal');
});

In this test we' re visiting the Dashboard page and we're checking if the medal card contains the text "You have won gold medal".
Playwright provides many ways to select elements, in our case we're using CSS selectors to find the card element in the page.

tests/analytics.spec.js

const { test, expect } = require('@playwright/test');

test.use({ storageState: 'tests/state.json' });

test('analytics', async ({ page }) => {
  await page.goto('https://pixinvent.com/demo/vuexy-vuejs-laravel-admin-template/demo-1/dashboard/analytics');
  await page.click('text=Add Record');

  const title = await page.locator('h4.invoice-title');
  await expect(title).toContainText('Invoice');
});

In our second test we visit the Analytics, click on the "Add Record" button and the check if the text "Invoice" appears inside a h4 element on the next page.
Notice that we don't have to write any specific method call for navigation, Playwright auto-waits for the next page.

Run the tests

In order to tun our tests we can use the commands we added in our package.json

npm run test

We can also run the tests in debug mode. This will open up the browsers in headed mode and also start the Playwright Inspector. Useful when we want to troubleshoot our tests scripts.

# For Linux and MacOS
npm run test-debug

# For Windows
npm run test-debug-windows

Useful commands

Here's a list of commands that can be useful when writing and running/debugging our test scripts

# Run a single test
npx playwright test testName

# Run in headed mode
npx playwright test --headed

# Run tests using a specified browser
npx playwright test --browser=firefox

# Run tests using all three browsers
npx playwright test --browser=all

That's all
Thanks for reading and have fun testing with Playwright!

How to create a Vue.js 2 / Bootstrap 4 project with Vite

Giannis Koutsaftakis — Wed, 25 Aug 2021 20:19:59 +0000

Vite is a lightning-fast dev environment and a pre-configured bundler into one. While it was first created to facilitate Vue.js 3 development, it can also be used for React, Svelte, Vanilla JS, and Vue.js 2.

There are plenty of tutorials for using Vite with Vue.js 3 and a lot of ready-made starter templates as well. We will be focusing on Vue.js 2 and see how we can create a base for a new project that:

Uses Bootstrap 4.6 CSS for layout and styling
Uses vue-router for client-side routing
Supports global SCSS variables inside Vue components
Is IE11 compatible
Removes unused CSS rules from the production bundle

Let's get right to it then!

Create a new Vite project

Although Vite contains many template presets out-of-the-box, it doesn't have one for Vue.js 2. We'll use the vanilla preset and then add the necessary plugins for Vue.js 2 development on top.

Navigate to your projects' directory and run:

Make sure you replace my-vue-app with your project's name.

npm 6.x

npm init vite@latest my-vue-app --template vanilla

npm 7+ (extra double-dash is needed)

npm init vite@latest my-vue-app -- --template vanilla

Install plugins needed for development

npm i -D vite-plugin-vue2 @vitejs/plugin-legacy vite-plugin-html vue-template-compiler sass@~1.32.13 postcss @fullhuman/postcss-purgecss autoprefixer

vite-plugin-vue2 - Vue.js 2 plugin for Vite
@vitejs/plugin-legacy - Support for legacy browsers (IE11)
vite-plugin-html - Minification and EJS template-based functionality for index.html
vue-template-compiler - Pre-compiles Vue.js 2 templates into render functions
sass - Pre-processor for SCSS, we need version 1.32 to avoid a SASS deprecation warning that affects Bootstrap 4
postcss - Transforms styles with JS plugins
@fullhuman/postcss-purgecss - PostCSS plugin that removes unused selectors from our CSS
autoprefixer - PostCSS plugin that adds vendor prefixes to CSS rules, also needed by Bootstrap

Install Dependencies

Install Vue.js, Vue Router, and Bootstrap

npm i vue vue-router bootstrap@4.6.0

We are using Bootstrap 4 since we want our project to be compatible with IE11

Setup file structure

It's time to adjust our project's structure so that it resembles that of a vue-cli project.

Remove style.css and move main.js out of the root folder and inside the src folder. Then create the following file/folder structure.

Don't worry about the files' contents for now, as we are going to fill them up as we go, just create empty files making sure they are named correctly.

├── src
│   │
│   ├── components
│   │   └── <-- store your project's components here
│   │ 
│   ├── router
│   │   └── index.js
│   │ 
│   ├── scss
│   │   ├── app.scss
│   │   └── variables.scss
│   │ 
│   ├── views
│   │   ├── About.vue
│   │   └── Home.vue
│   │ 
│   ├── App.vue
│   └── main.js
│
├── favicon.svg
├── index.html
├── postcss.config.js
└── vite.config.js

index.html, main.js, and App.vue

Vite uses index.html as the entry point of the application, We'll replace the contents of index.html with the markup below. Notice the EJS style variables title and description as we're going to set them in vite.config.js next.

We include src/main.js as the only script tag and Vite will resolve our JS source code.

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <meta name="description" content="<%- description %>">
    <link rel="icon" type="image/svg+xml" href="favicon.svg" />
    <title><%- title %></title>
  </head>
  <body>
    <noscript>
      <strong>We're sorry but <%- title %> doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
    </noscript>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

src/main.js

import Vue from 'vue'
import App from './App.vue'
import router from './router'

new Vue({
  router,
  render: (h) => h(App)
}).$mount('#app')

src/App.vue

<template>
  <div id="app">
    <ul class="nav nav-pills container pt-2">
      <li class="nav-item">
        <router-link to="/" exact exact-active-class="active" class="nav-link">
          Home
        </router-link>
      </li>
      <li class="nav-item">
        <router-link to="/about" class="nav-link">
          About
        </router-link>
      </li>
    </ul>
    <router-view />
  </div>
</template>

<script>
import '@/scss/app.scss'
</script>

Vite config

The config file for Vite resides in the project's root. Here we're initializing the plugins for Vue.js 2 and IE11 compatibility as well as setting the title and description for our project.

We're also setting an alias of @ for the src folder and injecting SCSS variables globally so that they are accessible from inside Vue components.

vite.config.js

import { minifyHtml, injectHtml } from 'vite-plugin-html'
import legacy from '@vitejs/plugin-legacy'
const path = require('path')
const { createVuePlugin } = require('vite-plugin-vue2')

module.exports = {
  plugins: [
    createVuePlugin(),
    minifyHtml(),
    injectHtml({
      injectData: {
        title: 'ProjectName',
        description: 'A single page application created using Vue.js'
      }
    }),
    legacy({
      targets: ['ie >= 11'],
      additionalLegacyPolyfills: ['regenerator-runtime/runtime']
    })
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, '/src'),
      '~bootstrap': 'bootstrap'
    }
  },
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "./src/scss/variables";`
      }
    }
  }
}

PurgeCSS

Bootstrap contains a lot of classes, but since we usually use a small set of the framework a lot of unused styles will be included in our CSS file. Let's configure PurgeCSS so that unnecessary styles will be stripped out of the final build.

postcss.config.js

const IN_PRODUCTION = process.env.NODE_ENV === 'production'

module.exports = {
  plugins: [
    require('autoprefixer'),
    IN_PRODUCTION &&
      require('@fullhuman/postcss-purgecss')({
        content: ['./**/*.html', './src/**/*.vue'],
        defaultExtractor(content) {
          const contentWithoutStyleBlocks = content.replace(/<style[^]+?<\/style>/gi, '')
          return contentWithoutStyleBlocks.match(/[A-Za-z0-9-_/:]*[A-Za-z0-9-_/]+/g) || []
        },
        whitelist: [],
        whitelistPatterns: [
          /-(leave|enter|appear)(|-(to|from|active))$/,
          /^(?!(|.*?:)cursor-move).+-move$/,
          /^router-link(|-exact)-active$/,
          /data-v-.*/
        ]
      })
  ]
}

Bootstrap SCSS

Our app's SCSS is located in scss/app.scss file. Here we include all Bootstrap SCSS except functions, variables, and mixins, as these will go inside scss/variables.scss so that we can use them inside our Vue.js components without explicitly importing them.

scss/app.scss

// Bootstrap source files (except functions, variables, mixins)
@import "~bootstrap/scss/root";
@import "~bootstrap/scss/reboot";
@import "~bootstrap/scss/type";
@import "~bootstrap/scss/images";
@import "~bootstrap/scss/code";
@import "~bootstrap/scss/grid";
@import "~bootstrap/scss/tables";
@import "~bootstrap/scss/forms";
@import "~bootstrap/scss/buttons";
@import "~bootstrap/scss/transitions";
@import "~bootstrap/scss/dropdown";
@import "~bootstrap/scss/button-group";
@import "~bootstrap/scss/input-group";
@import "~bootstrap/scss/custom-forms";
@import "~bootstrap/scss/nav";
@import "~bootstrap/scss/navbar";
@import "~bootstrap/scss/card";
@import "~bootstrap/scss/breadcrumb";
@import "~bootstrap/scss/pagination";
@import "~bootstrap/scss/badge";
@import "~bootstrap/scss/jumbotron";
@import "~bootstrap/scss/alert";
@import "~bootstrap/scss/progress";
@import "~bootstrap/scss/media";
@import "~bootstrap/scss/list-group";
@import "~bootstrap/scss/close";
@import "~bootstrap/scss/toasts";
@import "~bootstrap/scss/modal";
@import "~bootstrap/scss/tooltip";
@import "~bootstrap/scss/popover";
@import "~bootstrap/scss/carousel";
@import "~bootstrap/scss/spinners";
@import "~bootstrap/scss/utilities";
@import "~bootstrap/scss/print";

// Other application-wide SCSS rules here...

Our variables.scss contains overrides of Bootstrap SCSS variables as well as our own.

scss/variables.scss

$primary: #42b983;
$body-color: #304455;
$info:    #73abfe;
$gray-100: #f6f6f6;
$text-muted: #4e6e8e;
$gray-900: #273849;
$dark: #273849;

@import "~bootstrap/scss/functions";
@import "~bootstrap/scss/variables";
@import "~bootstrap/scss/mixins";

$navbar-dark-color: rgba($white, .7);

Routing and Views

Finally, let's set up our routing and the contents of our two sample views Home and About.

src/router/index.js

import Vue from 'vue'
import VueRouter from 'vue-router'
import Home from '@/views/Home.vue'

Vue.use(VueRouter)

const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home
  },
  {
    path: '/about',
    name: 'About',
    // route level code-splitting
    component: () => import('@/views/About.vue')
  }
]

const router = new VueRouter({
  linkActiveClass: 'active',
  routes
})

export default router

src/views/Home.vue

<template>
  <div class="container">
    <div class="text-center">
      <h1>This is the home page</h1>
    </div>
  </div>
</template>

src/views/About.vue

<template>
  <div class="container">
    <div class="text-center">
      <h1>This is the about page</h1>
    </div>
  </div>
</template>

Develop and Build

In order to start developing we run the command

npm run dev

This will start the dev server on http://localhost:3000

For bundling our app for production we use the following command

npm run build

This will create all the build assets inside the dist folder ready for us to deploy anywhere we like.

Finally
If you found this how-to useful, make sure you check out vue-vite-starter-template, which also includes ESLint, Prettier, semantic-release, Jest for testing, and more...

Thanks for reading!

DEV Community: Giannis Koutsaftakis

How to use an object with v-model in Vue

Exploring the problem

The solution

Simplifying the solution with VueUse

Vue 3 TypeScript code snippets and tips

Define a component

Props validation

Define a template ref

Define a component ref (get the type of a component)

Generic component type

Easy wrapper components with defineModel

Working with disabled attribute inheritance

Get listeners like in Vue 2

Get all attrs without style and classes

Get only style from attrs

A simple Vue form validation composable with Zod

The idea / how it works

Validation modes

How to use

Live example

Extend Vue Test Utils - findByText

Create and register the extends file

findByText function

Details

Parameters

Return Value

Example

Final notes

Skeleton Loader using Vue & Tailwind

Tailwind to the rescue

Skeleton loader component

Customization with props and slot

Props

Slot

How to use

Text of various sizes

Card

Demo with examples

A Vue dropdown menu with Floating Vue & Tailwind

What we'll create

Dropdown component

Breakdown of the most important parts

Structure and Styling

Manual form input bindings in Vue.js

v-model under the hood

Manual binding examples

Checkbox

Radio

Using Axios in Nuxt with Composition API

Install Nuxt composition API

Install, setup, and configure Nuxt Axios

Create and customize the Axios instance

API functions

Use the API functions inside our components

Create a nice search bar UX with vue-search-input

UX (best) practices

Storybook

GitHub

Gmail

vue-search-input

Features at a glance

Installation and Usage

Customization with props and slots

Props

Slots

Demo with examples

How to handle loading progress flicker

What we'll build

Implementation

Options

Creating our loader

How to use

Getting started with Playwright E2E testing

Install dependencies

Configure

Create the tests

Run the tests

Useful commands

How to create a Vue.js 2 / Bootstrap 4 project with Vite

`findByText` function

Customization with `props` and `slot`

Customization with `props` and `slots`