prop sugar

[patak-dev]

I want to avoid commenting on the Ref Sugar RFC about this because it may interfere in the discussion about ref:. I tried to find if the following proposal was discussed before but I couldn't find public discussions about it. Sorry for the noise if this was already analyzed.

Context

In the RFC it is stated that

... we believe ref:'s ergonomics value outweighs the cost by a fair margin. This is also why we are limiting this proposal to ref: only, since ref access is the only problem that requires alternative semantics to solve.

I think that it is on point, but there is also an asymmetry in the usage of props in the template and in the <script>. For simple components, we would end up with:

<script setup="props">
  export default { 
    props: {
      num: { type: Number, default: 4 }
    }
  }
  ref: multiplier = 2
</script>
<template>
  <p @click="multiplier++">{{ `${num} by ${multiplier} = ${num*multiplier}` }}</p>
</template>

With ref sugar, we can move the onClick handler to the script without the .value. But if we want to move the multiplication out of the template, we can not directly copy it in a computed, because we need to add the props.

<script setup="props">
  import { computed } from 'vue' 
  export default { 
    props: {
      num: { type: Number, default: 4 }
    }
  }
  ref: multiplier = 2
  ref: result = computed( () => props.num * multiplier )
</script>

We could convert the prop to a ref, taking care not to lose reactivity while destructuring (this is also something that we need also when passing the props to composables). We also need to explain what toRefs is achieving and the prop name needs to be repeated.

<script setup="props">
  import { computed, toRefs } from 'vue' 
  export default { 
    props: {
      num: { type: Number, default: 4 }
    }
  }
  ref: ({ num } = toRefs(props))
  ref: multiplier = 2
  ref: result = computed( () => num * multiplier )
</script>

The DX also suffers from extra boilerplate needed in this case. If ref: ends up being adopted, I think that having better ergonomics for props could also outweighs the cost of adding new syntax.

Proposal

Following the same model as ref:, we introduce a new label prop: to declare components props:

<script setup>
  import { computed } from 'vue'
  prop: num = 4
  ref: multiplier = 2
  ref: result = computed( () => num * multiplier )
</script>

When a prop is defined in this way, you can directly use its value in the template and in the script, and reactivity works properly.

Edited:
We could add a defineProp type-only helper to support complex validation of props:

<script setup>
import { defineProp } from 'vue'

prop: num = 4

prop: msg = defineProp({
  type: String,
  required: true
  validator: (val) => ![""].includes(val)
})
</script>

Implementation

• When a variable is declared using prop:, it is aggregated to the props block of the component.
• Every place where the variable is used it is replaced with props.num.
• In the same way that with ref:, if you use $num it is replaced with toRef(props,'num'), so you get a ref that you can pass to composables. If a different syntax is pushed to get the reference from ref:, that will be the syntax for prop: too (the important part is that they work in the same way).

Benefits

• Boilerplate is greatly reduced
• Code that uses props can be moved from template and script without modifications to a computed
• Getting a ref out of any reactive value (ref or prop) works in the same way (using $var, no need to explain toRefs and why reactivity is lost when destructuring right away when learning)
• If you need to lift state (a ref) to become a prop, you can change ref: with prop: and refactoring is easier because you do not need to add props. and toRef in all the places the prop is being used.
• props related to different features can be moved next to the code that uses them, making refactoring easier also for props (like splitting a component for example). It is the same principle used to justify ref, computed instead of the options API
• Using prop: is optional, if you want a custom validator for example you can declare that props in the normal props block
• We can use the same scheme for declaring default values and variable types used by svelte for props (looks like typescript support works fine for them now)

Cons

• Cost in tooling to support the new syntax (it should be similar to the cost of ref:).
• Extra syntax to explain, same as with ref:

Alternative

• In case using prop: wants to be avoided, export let could be used to declare props as svelte does. But I think that prop: plays better with ref: for Vue.

[dajpes]

I really like the prop label, what if we wanna declare many props like this:

<script setup>

prop: num= {
      type:Boolean,
      default:4}
prop: msg= {
      type:String,
      required:true
      validator:(val) =>  ![""].includes(val)
}
</script>

[patak-dev]

@dajpes now that the <script setup> RFC uses definedOptions and I think that also defineProps are being considered given this commit to Volar by @johnsoncodehk we may have a good way to define multiple complex prop: based props using:

<script setup>
import { defineProp } from 'vue'

prop: num = 4

prop: msg = defineProp({
  type: String,
  required: true
  validator: (val) => ![""].includes(val)
})
</script>

So we can still define each prop: next to the code it is related to if we want, and we do not need to fallback to defineOptions or defineProps for complex prop definition.

People could also use prop: together with defineProps like you spread multiple ref:s

<script setup>
import { defineProps } from 'vue'

prop: ({ num, msg } = defineProps({
  num: { 
    type: Number, 
    default: 4
  }, 
  msg: {
    type: String,
    required: true
    validator: (val) => ![""].includes(val)
  }
}))
</script>

[johnsoncodehk]

@dajpes now that the <script setup> RFC uses definedOptions and I think that also defineProps are being considered given this commit to Volar by @johnsoncodehk we may have a good way to define multiple complex prop: based props using:

A supplement*
I was follow the discuss to commit, so everything will change, currently volar is only support defineOptions, defineProps will be support if it become a consensus.

[patak-dev]

For reference to this discussion, the <script setup> RFC has been updated to use defineProps

[johnsoncodehk]

Sorry forgot to reply... I already added IDE support for defineProps. Please use volar if want to try.

[ghost]

为了便于参考，<script setup>RFC已更新为可以使用defineProps

 import { defineProps } from 'vue'

  prop: ({ num, msg } = defineProps({
    num: {
      type: Number,
      default: 4,
    },
    msg: {
      type: String,
      required: true,
    },
  }))

I wrote like above and reported an error defineProps is not defined

[ausgomez]

the way I am declaring props with sugar setup is like this:

<script setup>
const props = defineProps({
    num1: {
        type: Number,
        default: 6
    },
    num2 {
        type: Number,
        default: 8
    }
})
</script>

This seems to work fine, and you can call those values on the <template> like {{ num1 }}

Hope it helps

[HoraceKeung]

I am having a thought about the fact that one advantage of composition API is that you can group codes together by feature, but currently with defineProps, all props will be grouped together in one place.

<script setup>
const props = defineProps({
	prop1: { type: String, default: 'default' },
	prop2: { type: Number, required: true },
	prop3: String,
	prop4: { type: Boolean, default: false }
})
</script>

Then from #369, we have $ref and $computed, etc. This makes me think, would it be nice to have $prop and to define a prop we can do something like:

<script setup>
const prop1 = $prop({ type: String, default: 'default' })
const prop2 = $prop({ type: Number, required: true })
const prop3 = $prop(String)
const prop4 = $prop({ type: Boolean, default: false })
</script>

this way we can put our props anywhere we want.

[patak-dev]

I didn't update this issue so far because I was waiting for ref sugar to stabilize. I still think that this would be good for the reasons you state here (ability to group together logic for related features). There was a comment from Evan in another issue saying that he is already thinking about allowing sugary destructuring for defineProps. That would take care of the other main point in the original proposal (be able to move logic between template and script without adding props., same as the rationale for .value):

const { prop1, prop2, prop3, prop4 } = defineProps({
	prop1: { type: String, default: 'default' },
	prop2: { type: Number, required: true },
	prop3: String,
	prop4: { type: Boolean, default: false }
})
</script>

I think this would already be a big improvement. A problem I see is that with this, we end up repeating a lot the variable names, and more with TS and withDefaults, where we will need them three times:

interface Props {
  msg?: string
  labels?: string[]
}

const { msg, labels } = withDefaults(defineProps<Props>(), {
  msg: 'hello',
  labels: () => ['one', 'two']
})

I think that a $prop() macro would help here, the following code could be compiled to the one above avoiding the need for repeated variables:

<script setup>
const prop1 = $prop<string?>({ default: 'default' })
const prop2 = $prop<number>({ required: true })

const prop3 = $prop<string>()
const prop4 = $prop<boolean?>({ default: false })
</script>

[julie777]

vs const prop1 = $prop<string?>({ default: 'default' })

Why not just allow defineProps to be used multiple times with each use adding to the previous use. That wouldn't break the existing code or cause any interface changes. It would allow dividing separate functionality in script setup and make it easy to extract functionality to separate files.

I am in strong support of adding defaults and validators to defineProps. I think withDefaults seems like an afterthought. It would be nice if defineProps worked like composition api props and it actually seems to when I have volar convert <script> to <script setup>

<script setup> is awesome!

[yyx990803]

FYI vuejs/core#4690

With destructuring you already get default values + local aliasing for free:

const {
  foo,
  bar = 123, // default value
  baz: qux = 234, // aliasing + default value
  ...rest // rest spread also supported
} = defineProps<{ foo: string, bar?: number, baz?: number }>()

watchEffect(() => {
  console.log(foo) // will log every time foo changes
})

Caveats

Passing a destructured prop to a function

This is similar to ref sugar - essentially you need to wrap it in a getter or computed if you want to pass it and retain reactivity:

watch(() => destructuredProp, prop => {})

useSomeFeatureThatExpectsRef(computed(() => destructuredProp))

[jods4]

It actually gets compiled into real prop default options.

You went the extra mile! That's nice 👍

The same code would work previously, just without reactivity. In fact, few users would do destructuring with defineProps due to the reactivity issue. The only case where it would break is a user intentionally destructuring to get a static initial prop value, AND the parent actually passes dynamic props. I believe this is an extremely rare case.

I don't know how common it is but it's definitely a breaking change.
I have code like this, e.g. for components that want to highlight when their current "value" is different from the one at loading time.
The component starts by capturing the initial value(s) with code like const { data: initial } = props and then goes on to compare initial and props.data.
Please make a big warning when you introduce this change.

Prop keys are static so there are never new keys appended.

Good to know, I did not know that!
This makes the "default value" syntax behave unlike real JS but that's a small price to pay compared to the great syntax IMHO. 👍
(The diff. being that JS default values only apply to missing keys, not to keys equal to undefined)

Just for my own knowledge, can you confirm:

• Vue default values are applied to any props equal to undefined, even if it's set explicitely by a binding? (so null is preferred)
• There's no way to tell if a props has been bound or not?

You can already do computed(() => destructuredProp). We can also make the $$ sugar work with destructured props.

When I wrote conveniently, I was leaning towards the latter. 😃

Regarding merging this with ref sugar / making $ work on reactive objects: I'm also starting to think this might be eventually necessary.

👍

The reason I kept it separate from ref sugar is because this is more component specific and the underlying transform logic for is quite different.

I've seen that you desugar props variables into props.xyz instead of creating a new local ref.

At the moment, I think this is more an implementation detail that users don't necessarily need to know about.
On the surface, they both enable users to work with reactive values as if they were plain variables and I think that warrants sharing a common mental model and API for users.
The fact that they're transformed differently is, as I said, an implementation detail. For all users know, you could be creating passthrough refs variables to the props, as toRefs does.

This is gonna turn out great BTW 🎉

[yyx990803]

The component starts by capturing the initial value(s) with code like const { data: initial } = props and then goes on to compare initial and props.data.

The proposed destructure currently only applies to the defineProps call and not for destructure applied to the returned props object, so your use case actually isn't affected. But thinking about this, it does feel a bit inconsistent so maybe requiring explicit $() call will result in less ambiguity.

The diff. being that JS default values only apply to missing keys, not to keys equal to undefined

FYI JS default values work on both missing keys AND undefined...

const { a = 1 } = { a: undefined }
console.log(a) // 1

The default behavior will be consistent between props destructure and plain JS.

[jods4]

The proposed destructure currently only applies to the defineProps call and not for destructure applied to the returned props object, so your use case actually isn't affected. But thinking about this, it does feel a bit inconsistent so maybe requiring explicit $() call will result in less ambiguity.

Given that it would only apply to the initial defineProps call, you are right: the risk of regression is low because it would mean the component has no other props and destructures constant props even though their binding changes...

It feels a bit inconsistent that those two don't behave the same:

// Reactive
const { x } = defineProps();

// Not reactive
const props = defineProps();
const { x } = props;

Another detail this made me realize: I love the new syntax to apply default values, but using it means it's impossible to grab the complete props object.
I see you support the ...rest syntax, but I can't define a default value for props count, and have it in rest object.

const { count = 0, ...props } = defineProps<{ count: number; name: string }>()

props.count // == undefined

Most of the time this is not a big issue, but it's a little annoying if you want to pass around a reactive object that has count and name.
Might be nice to have a way to grab back the full props object.

FYI JS default values work on both missing keys AND undefined...

Right!
And I even tested it to be sure before writing my comment... 😂
Don't know what I did but I tested again and it applies to undefined indeed!

[Tenrys]

What is the recommended way to use a destructured prop inside of a $computed getter?

const { modelValue } = defineProps(["modelValue"]);
const emit = defineEmits(["update:modelValue"]);

let test = $computed({
  get: () => modelValue,
  set: val => emit("update:modelValue", val)
});

I don't believe this works and it looks more verbose than it needs to be...?

[jods4]

@Tenrys I don't see how you could make that getter shorter.

EDIT
I hadn't seen #413 when writing this comment and a lot of what's below is redundant with it.
I'm not deleting it but it's not worth the read now. I'll move the gist of what remains in #413.
/EDIT

First reflex was to say: "but I would write a reusable function for that" and when writing the code I noticed it isn't as nice as I'd thought.

// That's how you'd define it
function modelComputed(r /* : Ref */, emit, name) {
  return computed({ 
    get() { return r.value }, 
    set(val) { emit("update:" + name, val) },
  })
}

// That's how you'd use it
const { modelValue } = defineProps(["modelValue"]);
let test = $(modelComputed($$(modelValue), emit))

I think it's a lot of nested function calls/ceremony for what feels like one simple operation.
And that's assuming $$ works with destructured props and returns a ref proxy to the prop.

Interestingly a version that takes the full props object is a little simpler to use:

let test = $(modelComputed(props, emit))
let test2 = $(modelComptued(props, emit, 'notModelValue'))

That's nicer, but I pointed out in my previous comment that the current props destructuring proposal doesn't allow you to grab both the full props object and destructure all its values.

I think that can be solved by introducing a macro that destructures a reactive object (aka toRefs sugar) so (a) it can be applied to any reactive object; (b) we can split the props in 2 assignments:

const props = defineProps() // full object
const { modelValue } = $toRefs(props) // sweet variable for props access

// Direct destructuring remains sugar for $toRefs(defineProps())
const { modelValue } = defineProps()  // still sweet variables, but no full props variable

The other $ wrapping a common abstraction like modelComputed nags me a bit, too.
I think modelComputed(props, emit) |> $ reads better / more flat but it'll be a while before JS does this.

I would appreciate if I could configure the compiler to understand $model() as $(model(..)), my proof of concept was built with this configurability in mind but Evan said he's against this idea.

@yyx990803 Here's a less configurable variation on this idea: when calling an undefined function whose name starts with $, the compiler replaces it with $(f(..)).
For the result to work, because there's no magic configuration, f needs to have been imported (which creates a tooling problem for unused imports, but no worse than script setup already does); and for TS I would need to define $f globally in my project.

// My own globals.d.ts
define function $model(...)

// component.vue
import { model } from "./utils"
const x = $model(props, emit) // understood by compiler as $(model(props, emit))

[julie777]

As a voice of a user without the knowledge and history the rest of you have, and someone who hasn't used typescript,
I really don't like withDefaults as a separate function. I don't understand why it would be necessary.
I am using defineProps in <script setup> with default, types, etc. in my current js code.

[yyx990803]

withDefaults was provided as a way to provide default values when using pure TS interface props declarations, since there is no way to declare runtime values in TS type annotations. But with the props transform it will likely no longer be necessary in the future.

[trydofor]

how to use this sugar to replace withDefaults(defineProps<>(),{}) in ts

[jods4]

@trydofor the current plan is that JS destructuring default would be understood as props default values:

// max props has default value 10
const { max = 10 } = $(defineProps<{ max: number }>())

It's a really neat syntax. At this point it's unclear to me how we could get rid of withDefaults if we want to full props object and not destructure.

[bjarkihall]

If I understand this, then these are the current ways to declare props with default values:

JS:

const props = defineProps({ foo: { type: String, default: '' }, bar: { type: Number, default: 0 } })

TS:

const props = withDefaults(defineProps<{ foo?: string, bar?: number }>(), { foo: '', bar: 0 })

Destructured props (TS):

const { foo = '', bar = 0 } = defineProps<{ foo?: string, bar?: number }>()

But wouldn't this be possible? (maybe with a better/shorter name)

const props = definePropsWithDefaults({ foo: '', bar: 0 })

It has less control but it should be the most common way of defining simple props and it's not as repetitive as the other ones. It just abstracts withDefaults(defineProps<Partial<typeof args>>(), args).

If there's a default value, can't the type just be inferred?

The thing I'm trying to point out here is that we need to type each prop name two times: one for the type and the other for the default value. Is this really necessary? (since TS can infer the type from the default value)

const { foo = '', bar = 0 } = defineProps() // can the exposed props be inferred from the destructuring?
const props = defineDefaultProps({ foo: '', bar: 0 }) // { foo: { type: String, default: '' }, bar: { type: Number, default: 0 } }

[LifeIsStrange]

@yyx990803 Regarding the new destructuring syntax, it seems be unusable with object that have default values..

const {
  foo = {
    a: "a in child",
    b: "b in child",
  },
  c
} = defineProps<{ foo: { a?: string, b?: string }, c?: string }>()

The parent sends:

<Test :foo="{b: 'b from parent component'}"/>

When I print foo:
the resulting output is {b: 'b from parent component'}
the expected output is {a: 'a in child', b: 'b from parent component'}

I hope Vue can define a clean syntax that allow the simple and common needs that is: to have props that are objects and that (at least some) keys have default values.

[jods4]

I think that'd be expected:

Props are a flat dictionary of key-values, that can have defaults.

Your example looks like you wanted to have default values for "props" foo.a and foo.b but it doesn't work like that.

Your component has only 2 props: foo and c.
You have declared a default value for foo, with value { a: "a in child", b: "b in child" } that will be used if foo is not bound.

Your parent actually provides a :foo="{ b: 'b from parent' }", so the default is not used.

There's no kind of "deep-merging" applied to props default values.
If you want this kind of custom behavior you'll need to code it.

[nicolidin]

Actually @LifeIsStrange I don't even know how to make this behaviour works using withDefault(). If anyone knows I would like to know how.
I explain it :

//Component Foo
interface Props {
  mainPayload: {
    color: string,
    alt: string,
    size?: "small" | "medium" | "big"
  }
}

const props = withDefaults(defineProps<Props>(), {
  mainPayload: (it) => {
    return {
      ...it.mainPayload,
      size: "small",
    }
  }
});

console.log("props: ", props)

If I call foo component in Home like below:

<!--  Home -->
<Foo :mainPayload="{color: 'red', alt: 'I will sadly never see about size:('}"/>

The console.log of props in the Foo component will sadly only show color and alt but not size.

[posva]

you need to split it up into 3 props or at least, put the optional props on their own, so mainPayload: {color: string; alt: string} and size?: 'small' | ....

If you want a partial prop, you can override it with a computed

[nicolidin]

No but we have to imagine that mainPayload corresponds to a model so I can't extract properties from it.

But thanks, I didn't know about the override computed way ! It indeed works well:)

[LifeIsStrange]

@posva
Thanks, about the first suggestion:

you need to split it up into 3 props or at least, put the optional props on their own

This is a bad limitation that breaks the semantics/encapsulation of our objects.

If you want a partial prop, you can override it with a computed

Thanks ! This is an interesting workaround, the syntax is concise but

1. using a computed for this does not seems intuitive
2. does it has performance/behaviour implications?

The biggest limitation of this approach is that the default value of the object (in the computed), need to be defined outside of the defaults values of non-object props, contrary to @nicolidin Withdefaults approach.

I'm pretty sure Vue could define a clean and concise syntax that works well for objects without the needs of such unintuitive and limited workaround, for example Vue could at runtime use reflection to iterate recursively over object Props to check wether a key is missing. If it is missing then Vue would apply the default value. That seems intuitively very much feasable and would signfiicantly improve props ergonomics overall (much more easily discoverable than computed, less surprising, no breaking of encapsulation and duplicate declaration of a default values block).

[theoephraim]

Great discussion here and regardless of the syntax, the ability to split up individual props into individual definitions is going to be great for DX and to match the rest of the new composition stuff. It would be great if individual props could be extracted into other files / composition functions as well (ie useSomeFeatureThatAddsProps()) rather than being limited to be in the setup function itself.

Forgive me if what I'm writing below is a little off topic, but it seems there is a lot of related discussion here.

I'm curious what the reason is for focusing on defining props using the type-only syntax? I get the impression the core team may be pushing for this to be the preferred / idiomatic way when using TS. While obviously no one likes the withDefaults solution, the new proposed destructuring based solution IMO also has a large drawback - it splits up the default value from the definition of the prop.

This isn't great for readability when you have a lot of props, it forces you to destructure the prop, and it's also more awkward to extract sets of shared props.

With the object based syntax, I can extract a set of related props (including default values) that may be reused into an object and use it in several components. I can even use functions that generate a set of props. For example:

const props = defineProps({
  ...commonSizeProps,
  ...getCommonColorProps('dark'),
  propForJustThisComponent: { type: String as PropType<'foo' | 'bar'>, default: 'foo' },
});

This plus the fact that it supports all features (including arbitrary validation functions) makes me think the object syntax should just be the standard way of doing things (even in TS) and that the type-only syntax should be discouraged or even deprecated entirely. I'll admit it's slightly more verbose, but not prohibitively so and I think quite clear.