VueJS

Vue 3 Composition API: How to Omit `.value` in refs

Published May 13, 2022

Updated Nov 22, 2023

6 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

NOTE: The "reactivity Transform" RFC has been concluded and the team has decided not to go ahead with this. The information in the following post are informative to learn what was being discussed, but will not be usable as this feature is not going to be added within the Vue framework.

In this article, we discuss how to omit .value in VueJS refs, creating APIs by converting them into reactive variables using macros.

Introduction

When Vue 3 first came around, it introduced the Composition API. The API permitted greater code re-usability, and provided a better way to organize Vue JS code. Along with the composition API came the concept of refs. To access the value of a ref, you needed to append .value to the name of the ref variable. To tackle this, the Vue team came up with a solution (Reactivity Transform) that would allow us to create reactive variables without creating refs.

Prerequisites

This article is primarily aimed at intermediate Vue 3 developers, and assumes three things:

Intermediate knowledge of JavaScript
Basic Vue 3 skills
A basic understanding of how to use refs and reactivity in Vue

The functionality discussed in this article is purely opt-in, and existing behavior is unnafected.

Tools needed

For this to work, you will need to be using vue@^3.2.25 and above. No additional dependencies are required. Vue 3.2.25+ ships an implementation under the package @vue/reactivity-transform. It is also integrated (with its APIs re-exported) in @vue/compiler-sfc, so most userland projects won't need to explicitly install it.

Reactivity in Vue 3

Reactivity refers to the ability to keep track of changes that occur in our applications. One such way to achieve reactivity in Vue 3 is by using refs.

Creating Refs

The syntax for creating a ref would be something along the lines of this:

import { ref } from "vue";

// By wrapping our default value (true) with a ref, we tell Vue to keep track of changes made to it
const isReading = ref(true);

This means that when the value of isReading changes, Vue knows about it, and it can keep track of the changes. This means that the UI is automatically updated whenever the value of isReading changes. In your template file, you would access the reactive value the same way you would access any variable. For example:

<template>
  <h1>{{ isReading ? "Shhh, I'm reading" : "Talk to me" }}</h1>
</template>

Using refs

That's all fine and dandy, but when you want to access or modify the value of the refs in the script, you need to append a .value at the end of it. This is because ref() wraps the actual variable(isReading) in an object that can keep track of any changes made to it.

import { ref } from "vue";

const isReading = ref(true);

// prints an object that represents the ref object that wraps isReading
console.log(isReading);

// This is how you would need to access the value of isReading
console.log(isReading.value); // prints true

Reactivity Transform

Removing the need for `.value`

The new Vue 3 syntax allows you to use refs without needing to use .value. To make this work, the Vue team implemented Reactivity Transform. This allows us to create reactive variables for every API that creates refs instead of using refs. This means we can use our variables without appending .value everywhere. Reactive variables do not need .value to be accessed while refs need you to append .value.

Previously, we used to write code like this

const isReading = ref(true);

console.log(isReading.value);

which can now be written like this

// Prepending $ to ref makes $ref() a macro that wraps around the original ref()
const isReading = $ref(true);

console.log(isReading); // no need to write

Behind the scenes, Vue will unwrap the $ref() and compile into the original .value syntax we are used to writing. The only difference is that this time you don't have to write isReading.value everywhere. This is particularly useful in areas where the ref created is used in multiple places within a script.

It is also worth noting that every reactivity API that returns refs will have a $-prefixed macro equivalent. These APIs include:

ref -> $ref computed -> $computed shallowRef -> $shallowRef customRef -> $customRef toRef -> $toRef

Do you need to import `$ref` ?

Since $ref and equivalents are macros, they do not need to be imported. However, if you would like to import them explicitly, you can do so from vue/macros.

import { $ref } from "vue/macros";

Convert an existing ref as reactive variable using `$()`

In situations where we have a function that returns a ref, the Vue compiler would not be able to know that the function will return a ref ahead of time. In such cases, we can wrap the function call with $() to explicitly convert it into a reactive variable.

function getIsReadingRef() {
  return ref(true);
}

const isReading = $(getIsReadingRef());

Destructuring objects of refs

Previously, if you tried to destructure an object that was a ref, the destructured variables would lose their reactivity.

Let's go with an example ref.

const getDefaultReader = () => ref({ name: "VueJS lover", timeOnPage: 30 });

// Vue will be able to tell when any part of `reader` changes
const reader = ref(getDefaultReader());

// Vue won't be able to tell when the values of `name` and `timeOnpage` change
const { name, timeOnPage } = ref(getDefaultReader());

With Reactivity transform, you can destructure the objects of refs and maintain reactivity. You do so by wrapping the value with a $().

// Vue will now be able to tell when the values of `name` and `timeOnpage` change
const { name, timeOnPage } = $(getDefaultReader());

The above code will compile to:

const __temp = getDefaultReader(),
  name = toRef(__temp, "name");
timeOnPage = toRef(__temp, "timeOnPage");

Reactive props destructuring

This example is from the original Reactivity Transform RFC.

There are two pain points with the current defineProps() usage in <script setup>

Similar to .value, you need to always access props as props.x in order to retain reactivity. This means you cannot destructure defineProps because the resulting destructured variables are not reactive and will not update.
When using the type-only props declaration, there is no easy way to declare default values for the props. We introduced the withDefaults() API for this exact purpose, but it's still clunky to use.

<script setup lang="ts">
interface Props {
  msg: string;
  count?: number;
  foo?: string;
}

const {
  msg,
  // default value just works
  count = 1,
  // local aliasing also just works
  // here we are aliasing `props.foo` to `bar`
  foo: bar,
} = defineProps<Props>();

watchEffect(() => {
  // will log whenever the props change
  console.log(msg, count, bar);
});
</script>

The above will be combined to the following in runtime.

export default {
  props: {
    msg: { type: String, required: true },
    count: { type: Number, default: 1 },
    foo: String,
  },
  setup(props) {
    watchEffect(() => {
      console.log(props.msg, props.count, props.foo);
    });
  },
};

Using $$() to retain reactivity

To get around reactivity loss in certain scenarios, the $$() macro can be used.

Retaining reactivity when passing refs as function arguments

Consider a situation where you have a function that needs to accept a reactive variable as an argument.

function trackChange(isReading: Ref<boolean>) {
  watch(isReading, (isReading) => {
    console.log("isReading changed!", isReading);
  });
}

let isReading = $ref(true);

// This will not work
trackChange(isReading);

In such a case, reactivity is lost.The reason for this is that the isReading ref is actually unwrapped into isReading.value when being passed in as the argument for trackChange, while trackChange expects an actual ref. The above code compiles to this:

import { ref } from "vue";

let isReading = ref(true);

// This is what is actually happening
trackChange(isReading.value);

To get around this, we can wrap the ref in $$(), which tells the compiler not to append a .value to it.

// This will work
trackChange($$(isReading));

The above example compiles to this:

import { ref } from "vue";

let isReading = ref(true);

// This is what we want - the isReading variable should be passed as a ref
trackChange(isReading);

Retaining reactivity when returning inside function scope

Another scenario where reactivity is lost is when we are returning reactive variables from within a function.

function useMouse() {
  let x = $ref(0);
  let y = $ref(0);

  // listen to mousemove...

  // doesn't work!
  return {
    x,
    y,
  };
}

Similar to the example with passing refs as arguments, the above return statement compiles to:

return {
  x: x.value,
  y: y.value,
};

In order to maintain the reactivity of x and y, we can wrap the entire return statement with the $$() macro.

function useMouse() {
  let x = $ref(0);
  let y = $ref(0);

  // listen to mousemove...

  // This works
  return $$({
    x,
    y,
  });
}

Retaining reactivity on destructured props

$$() works on destructured props since they are reactive variables as well. The compiler will convert it with toRef for efficiency:

const { count } = defineProps<{ count: number }>();

passAsRef($$(count));

compiles to:

setup(props) {
  const __props_count = toRef(props, 'count')
  passAsRef(__props_count)
}

TypeScript & Tooling Integration

Vue will provide typings for these macros (available globally) and all types will work as expected. There are no incompatibilities with standard TypeScript semantics, so the syntax would work with all existing tooling.

This also means the macros can work in any files where valid JS/TS are allowed - not just inside Vue SFCs.

Since the macros are available globally, their types need to be explicitly referenced (e.g. in a env.d.ts file):

/// <reference types="vue/macros-global" />

When explicitly importing the macros from vue/macros, the type will work without declaring the globals.

Conclusion

By taking advantage of the macros added to Vue 3, you can drastically clean up your codebase by getting rid of .value usage. You also get to preserve reactivity within your application when destructuring reactive variables as well as props when using the Composition API and defineProps().

If you'd like to read more on the same, you can do so in the official Vue JS RFC discussion for the feature.

I do hope you find this helpful in reducing your code footprint, and making your general life easier. The next time you think of using .value for your refs, remember that you don't have to. With that, thanks for stopping by!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Allan M. Jeremy
Allan Jeremy is a self-proclaimed polymath, entrepreneur and Senior Software Engineer at ThisDot Labs. He is an AI and crypto enthusiast that loves to learn most things tech and business as well as sharing what he learns.
@theallanjeremy @AllanJeremy

Understanding Vue.js's <Suspense> and Async Components

In this blog post, we will delve into how and async components work, their benefits, and practical implementation strategies to make your Vue.js applications more efficient and user-friendly. Without further ado, let’s get started! Suspense Let's kick off by explaining what Suspense components are. They are a new component that helps manage how your application handles components that need to await for some async resource to resolve, like fetching data from a server, waiting for images to load, or any other task that might take some time to complete before they can be properly rendered. Imagine you're building a web page that needs to load data from a server, and you have 2 components that fetch the data you need as they will show different things. Typically, you might see a loading spinner or a skeleton while the data is being fetched. Suspense components make it easier to handle these scenarios. Instead of manually managing loading states and error messages for each component that needs to fetch data, Suspense components let you wrap all these components together. Inside this wrapper, you can define: 1. What to show while the data is loading (like a loading spinner). 2. The actual content that should be displayed once the data is successfully fetched. This way, Vue Suspense simplifies the process of handling asynchronous operations (like data fetching) and improves the user (and the developer) experience by providing a more seamless and integrated way to show loading states and handle errors. There are two types of async dependencies that can wait on: - Components with an async setup() hook. This includes components using with top-level await expressions. *Note: These can only be used within a component.* - Async Components. Async components Vue's asynchronous components are like a smart loading system for your web app. Imagine your app as a big puzzle. Normally, you'd put together all the pieces at once, which can take time. But what if some pieces aren't needed right away? Asynchronous components help with this. Here's how they work: - Load Only What's Needed: Just like only picking up puzzle pieces you need right now, asynchronous components let your app load only the parts that are immediately necessary. Other parts can be loaded later, as needed. - Faster Start: Your app starts up faster because it doesn't have to load everything at once. It's like quickly starting with the border of a puzzle and filling in the rest later. - Save Resources: It uses your web resources (like internet data) more wisely, only grabbing what’s essential when it's essential. In short, asynchronous components make your app quicker to start and more efficient, improving the overall experience for your users. Example: ` Combining Async Components and Suspense Let's explore how combining asynchronous components with Vue's Suspense feature can enhance your application. When asynchronous components are used with Vue's Suspense, they form a powerful combination. The key point is that async components are "suspensable" by default. This means they can be easily integrated with Suspense to improve how your app handles loading and rendering components. When used together, you can do the following things: - Centralized Loading and Error Handling: With Suspense, you don't have to handle loading and error states individually for each async component. Instead, you can define a single loading indicator or error message within the Suspense component. This unified approach simplifies your code and ensures consistency across different parts of your app. - Flexible and Clean Code Structure: By combining async components with Suspense, your code becomes more organized and easier to maintain. An asynchronous component has the flexibility to operate independently of Suspense's oversight. By setting suspensible: false in its options, the component takes charge of its own loading behavior. This means that instead of relying on Suspense to manage when it appears, the component itself dictates its loading state and presentation. This option is particularly useful for components that have specific loading logic or visuals they need to maintain, separate from the broader Suspense-driven loading strategy in the application. In practice, this combo allows you to create a user interface that feels responsive and cohesive. Users see a well-timed loading indicator while the necessary components are being fetched, and if something goes wrong, a single, well-crafted error message is displayed. It's like ensuring that the entire puzzle is either revealed in its completed form or not at all rather than showing disjointed parts at different times. How it works When a component inside the boundary is waiting for something asynchronous, shows fallback content. This fallback content can be anything you choose, such as a loading spinner or a message indicating that data is being loaded. Example Usage Let’s use a simple example: In the visual example provided, imagine we have two Vue components: one showcasing a selected Pokémon, Eevee, and a carousel showcasing a variety of other Pokémon. Both components are designed to fetch data asynchronously. Without , while the data is being fetched, we would typically see two separate loading indicators: one for the Eevee Pokemon that is selected and another for the carousel. This can make the page look disjointed and be a less-than-ideal user experience. We could display a single, cohesive loading indicator by wrapping both components inside a boundary. This unified loading state would persist until all the data for both components—the single Pokémon display and the carousel—has been fetched and is ready to be rendered. Here's how you might structure the code for such a scenario: ` Here, is the component that's performing asynchronous operations. While loading, the text 'Loading...' is displayed to the user. Great! But what about when things don't go as planned and an error occurs? Currently, Vue's doesn't directly handle errors within its boundary. However, there's a neat workaround. You can use the onErrorCaptured() hook in the parent component of to catch and manage errors. Here's how it works: ` If we run this code, and let’s say that we had an error selecting our Pokemon, this is how it is going to display to the user: The error message is specifically tied to the component where the issue occurred, ensuring that it's the only part of your application that shows an error notification. Meanwhile, the rest of your components will continue to operate and display as intended, maintaining the overall user experience without widespread disruption. This targeted error handling keeps the application's functionality intact while indicating where the problem lies. Conclusion stands out as a formidable feature in Vue.js, transforming the management of asynchronous operations into a more streamlined and user-centric process. It not only elevates the user experience by ensuring smoother interactions during data loading phases but also enhances code maintainability and application performance. I hope you found this blog post enlightening and that it adds value to your Vue.js projects. As always, happy coding and continue to explore the vast possibilities Vue.js offers to make your applications more efficient and engaging!...

Apr 24, 2024

6 mins

VueWeb PerformanceUXJavaScript

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

In this episode of the Modern Web podcast, Tracy Lee and Rob Ocel sit down with Sarah Shook, a UI/UX engineer at Hunter Industries. They discuss the topic of Sarah’s THAT Conference talk on color theory, exploring the intricacies of RGB, HSL, and hex color models. The discussion also touches on the importance of understanding how color accessibility impacts your page’s performance. Chapters - 00:00 - Introduction and Guest Introduction - 01:30 - Balancing Work and Parenthood - 03:20 - Family-Friendly Conferences and THAT Conference Experience - 05:45 - Overview of Sarah's Presentation on Color Theory - 07:00 - Understanding Additive and Subtractive Color Models - 09:00 - RGB to Hex Conversion Explained - 11:45 - Importance of Color Theory in Web Development - 14:00 - Accessibility and Color Luminescence - 16:00 - Tools and Resources for Color Accessibility - 18:30 - Sarah’s Experience with Vue and Other Frameworks - 21:00 - Discussion on Framework Deployment and Tooling - 23:15 - The Challenges and Benefits of Learning Multiple Frameworks - 25:00 - Tailwind, TypeScript, and Framework Preferences - 27:00 - Vue Community and Tooling Insights - 29:00 - Advanced JavaScript and TypeScript Content with DropJS - 31:00 - Sarah’s Color Utility Project and Where to Find Her - 32:30 - Closing Thoughts and Outro Follow Sarah Shook on Social Media Twitter: https://x.com/shookcodes Linkedin: https://www.linkedin.com/in/sarahshook/ Github: https://github.com/shookcodes Sponsored by Wix Studio...

Aug 27, 2024

1 min

JavaScriptVueReact

Layouts & Theming in Vuetify 3

Introduction Do you want to avoid tinkering with CSS to get your website looking just right? Branding is everything in today's digital landscape. With Vuetify 3's customizable theming options, you can create web projects that perfectly reflect your unique branding, and visual identity. Additionally, you can reduce the duplicated code by creating layouts representing your application's different page structures. In a previous article introducing Vuetify 3 with Vue 3, we created an application that allowed us to add, display, and delete jokes. If you'd like to follow along with this article, please clone the GitHub repository. ` In this article, we'll go over how you can create layouts in Vuetify 3 to allow you to reuse the same layout for pages that share the same structure. We will also go over how you can customize the look and feel of your application to match your brand's visual identity through the powerful theming tools that Vuetify 3 offers us. Layouts in Vuetify 3 What are layouts, and how are they useful? In web development, layouts are akin to blueprints for the structure of your web pages. They provide a consistent and reusable frame for the different pages of an application. A well-designed layout can improve the user experience by providing familiarity and predictability as the user navigates through other parts of your application. Layouts are particularly helpful in reducing code duplication. Instead of defining the same structure for each page—headers, footers, and navigation menus, you define them once in a layout, and then apply that layout to any page that uses the same structure. This speeds up development, and makes your code easier to maintain. Using Layouts in Vuetify 3 Creating a layout in Vuetify 3 is as simple as creating a new Vue component. This component will include the common elements shared across multiple pages like headers, footers, and navigation bars. Here is an example of a basic layout: ` This layout has a header, a navigation drawer, and a footer. The component is where the content of the specific pages will be injected. Building a layout for our application Let's create a layout for our application. We'll have a top navigation bar and a footer. Inside the layouts directory, create a new file named Default.vue and add the following code: ` Additionally, in order for us to use our layout, we will need to modify our router/index.ts file to use the Default.vue component: ` This will make sure that our respective pages use the Default.vue layout that we created. The contents of the pages will appear in place of in the layout. It is also worth noting that you can create, and nest as many layouts as you want. Theming in Vuetify 3 Themes allow you to customize your application's default colors, surfaces, and more. If your brand has specific colors and styling, you can theme your Vuetify application to resemble your brand through theming better. Additionally, Vuetify 3 allows you to modify your theme in real-time programmatically. [Vuetify 3] also comes with light and dark themes pre-installed. Theming API Vuetify 3 offers us 2 main APIs for working with themes: - useTheme is a composable that allows us to get information about the current theme and will enable us to modify the existing theme. - v-theme-provider is used in the section of your Vue files to modify the theme of all of its children. Updating the theme of our application Updating the theme of our application is straightforward with Vuetify 3. Let's customize our application's primary and secondary colors. In the vuetify.ts file, modify the themes section to contain the following styles: ` In this example, we're defining a custom 'light' theme. If you want to use a dark theme, or any other named theme, you can add those as additional properties within the themes object. For example: ` And... That's it! By changing the various config options in the vuetify.ts file, you can modify how your application looks and feels to match your brand. If you'd like to learn more about themes and all the options you can provide, please check out the official Vuetify documentation. Conclusion In this article, we've gone through the concepts of layouts and theming in Vuetify 3. We've seen how layouts can reduce code duplication, and provide consistency across your application. We've looked at how Vuetify's theming features allow you to customize your application to match your brand's visual identity. Understanding and utilizing these features effectively can significantly enhance the development experience and the end user's interaction with your application. Remember, a well-structured and visually appealing application not only attracts users, but also retains them. Happy coding!...

May 19, 2023

4 mins

Vue

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

In this episode of the Modern Web Podcast, Danny Thompson sits down with Ferdinand Como and Baptiste Leproux from Nuxt Labs to uncover the story behind Nuxt Studio, a tool that's transforming how developers and non-technical users interact with Nuxt applications. Ferdinand and Baptiste share how Nuxt Studio bridges the gap between developer customization and user-friendly content management. Built to empower agencies, freelancers, and their clients, Nuxt Studio combines powerful features like live previews, Vue component integration, and schema-driven forms to make managing content seamless. The conversation also explores the broader mission of Nuxt Labs—building sustainable open-source tools that enhance developer experience and meet real-world needs. With insights into the future of Nuxt Studio and its potential to scale for larger organizations, this episode is a must-listen for anyone passionate about innovation in web development. Chapters 1. Introduction and Setting the Stage (00:00:00) 2. The Vision Behind Nuxt Studio (00:03:10) 3. Nuxt Studio’s Core Features (00:08:45) 4. Challenges in Building Nuxt Studio (00:16:20) 5. Target Audience and Use Cases (00:22:35) 6. Sustainability in Open Source (00:29:00) 7. The Future of Nuxt Studio (00:35:10) 8. Nuxt Studio’s Role in the Nuxt Ecosystem (00:42:30) 9. Closing Thoughts and What’s Next (00:48:00) 10. Sponsor Shoutout and Wrap-Up (00:53:20) Follow Baptiste Leproux and Ferdinand Coumau Baptiste Twitter: https://x.com/_larbish Ferdinand Twitter: https://x.com/CoumauFerdinand Baptiste Linkedin: https://www.linkedin.com/in/baptiste-leproux-618842b0/ Ferdinand Linkedin: https://www.linkedin.com/in/ferdinand-coumau-nuxt/ Sponsored by This Dot: thisdot.co...

Nov 20, 2024

2 mins

VueNuxtJS

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Vue 3 Composition API: How to Omit `.value` in refs

Introduction

Prerequisites

Tools needed

Reactivity in Vue 3

Creating Refs

Using refs

Reactivity Transform

Removing the need for `.value`

Do you need to import `$ref` ?

Convert an existing ref as reactive variable using `$()`

Destructuring objects of refs

Reactive props destructuring

Using $$() to retain reactivity

Retaining reactivity when passing refs as function arguments

Retaining reactivity when returning inside function scope

Retaining reactivity on destructured props

TypeScript & Tooling Integration

Conclusion

Allan M. Jeremy

You might also like

Understanding Vue.js's <Suspense> and Async Components

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Layouts & Theming in Vuetify 3

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

Let's innovate together!

You might also like

Understanding Vue.js's <Suspense> and Async Components

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Layouts & Theming in Vuetify 3

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

Introduction

Prerequisites

Tools needed

Reactivity in Vue 3

Creating Refs

Using refs

Reactivity Transform

Removing the need for .value

Do you need to import $ref ?

Convert an existing ref as reactive variable using $()

Destructuring objects of refs

Reactive props destructuring

Using $$() to retain reactivity

Retaining reactivity when passing refs as function arguments

Retaining reactivity when returning inside function scope

Retaining reactivity on destructured props

TypeScript & Tooling Integration

Conclusion

Allan M. Jeremy

Understanding Vue.js's <Suspense> and Async Components

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Layouts & Theming in Vuetify 3

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

Let's innovate together!

Understanding Vue.js's <Suspense> and Async Components

Color Theory For Software Engineers + Color Accessibility & Performance with Sarah Shook

Layouts & Theming in Vuetify 3

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

Removing the need for `.value`

Do you need to import `$ref` ?

Convert an existing ref as reactive variable using `$()`