That would be a separate proposal - this RFC is strictly scoped to <script setup>.

That would be a separate proposal - this RFC is strictly scoped to SFCs.

Options API is available in SFCs. You mean it's only available for <script setup>.

Yes.

but if you provide a default value, you don't need required: true, do you? 🤔

@posva I recall for TS typing pre-setup and generics, you did, because required decides whether the type can be undefined.

// props.n: number | undefined = 0;
const props: { n: { type: Number, default: 0 } }

// props.n: number = 0;
const props: { n: { type: Number, required: true, default: 0 } }

As I said, maybe that's not super relevant for newer APIs, as in script setup I would do:

// This follows my TS generic type:
// n: number
// m: number | undefined
const { n = 0, m = 0 } = defineProps<{ 
  n: number, 
  m: number | undefined,
}>();

In what situation would a prop == undefined if a default is set?

@joezimjs nothing prevents you to explicitly bind an undefined value.

@jods4 I'm glad the required is no longer necessary now though 😆

A prop that accepts undefined will still take the default value if explicitly set to undefined as it's the same as not being passed at all Example

Is it implemented inside the core props code or as an extra layer

As an extra layer, with an additional ref and watchers. It works very similar to useVModel from VueUse.

If it's an extra ref layer, does it exist always or is the component checking whether the component is two-way bound?

It always exists if local: true is specified. Which is why it is false by default.

I assume that when model is assigned the same value (according to hasChanged) no event is raised (just like refs don't trigger)?

Correct.

Vue is lacking a way to extend hasChanged behaviour

An RFC is welcome. There are various aspects that need discussion. This can affect watchers, computed, and refs. Introducing extra options for each feels heavy handed, but a global option isn't flexible enough.

It does not emit, although if the object is deeply reactive then direct mutations should just trigger updates in parent without even emitting.

direct mutations should just trigger updates in parent without even emitting.

I'm fully aware of that, but I was always under the imporession that mutating prop's properties is not the best practice and you'd rather emit a new object with updated property. Not actually sure whether deep option is actually doing what I think it's doing

without even emitting

that's the point, this behavior breaks the consistency, some of the v-model's emit events, others not. I always end up defining a local state (based on the passed modelValue), mutating it and emitting to the parent as object. Although this generates boilerplate code, it ensures consistent behavior across all components. I think we still miss a better approach for this use case

Wait, an object prop's changes don't emit? 🤔 Seems like sticking with VueUse is the better option then.

Correct. If you want this level of control, just roll it yourself.

@joezimjs I'd recommend taking a look at: https://vueuse.org/core/useVModel/#usevmodel

Fixed in vite-plugin-vue v4.2.3

I have the same problem

Solved

On nuxt.config.ts:

 vite: {
    vue: {
      script: {
        defineModel: true,
      },
    },
  },

I've been searching for ages! Discord, YouTube, Google, even ChatGPT!!! Can't get this to work on Nuxt 3 or Vue.
Already installed all latest and beta versions of packages like vue, nuxt, @vue/compiler-sfc, vite. Attempted to override the packages in the package.json. defineModel is undefined when compiled to JS.

The one in the macros library works fine: https://vue-macros.sxzz.moe/macros/define-models.html

Just an aside, there is no way stock ChatGPT is going to be helpful about this: it's training data only goes up to 2021.

In a plain Vite project, updating vue and @vitejs/plugin-vue solved my issue.

For Nuxt users, it seems like you have to wait the soon-to-be-released Nuxt 3.5.

I got it working thanks to someone in Discord. Updated my reply.

From my personal experience with frameworks where it works like that, I never found it confusing nor have I seen someone say so.

In particular with defineProps destructuring experiment, I'd say this proposal is not any more hidden than defineModel.
At assignment site, both a destructured defineProps and defineModel would look identical, they're simple variable assignments. There's no telling sign that one raises an event and the other does not.
At declaration, I'd say that { model: true } is as explicit as definedModel, it is a simple marker with a clear meaning.

EDIT: I just realised the assignment site remark is is not 100% accurate. defineModel returns a ref so it'd be model.value = 1, whereas destructured props is just model = 1.
I'd see this as a benefit because just as we make one step towards plain variable for props, we're making one step back to ref and .value for models.

On the other hand, if the destructured props experiment is eventually dropped, assigning to props variable such as props.model = 1 is a very clear sign that you're sending an event, as props are otherwise be read-only.

Why not expose this idea as writable props?

I think it would make way more sense if it's all together instead of separated into two separate functions, and models are props anyway. though my idea was to have the options also be part of the type definition, if that's possible.

defineModel returns a ref so it'd be model.value = 1, whereas destructured props is just model = 1

But if it's model = 1 it can't be reactive? It can only be props.model = 1 or model.value = 1, there has to be some kind if property for it to be reactive/ref.

But if it's model = 1 it can't be reactive? It can only be props.model = 1 or model.value = 1, there has to be some kind if property for it to be reactive/ref.

There's an experimental feature in Vue 3.3 (has to be enabled with an option) that makes destructured props "magically" reactive.

// !! experimental, not yet for prod !!

// This code in your component:
let { model } = defineProps(...);
const x = model;
model = 42;

// Is transformed by compiler into
const x = props.model;
props.model = 42;

Personally I'm a fan of mutable props.

It's not "wrong" - it's just there to force the overload to be used when default is present. Because it's an intersection, the type constraints for default in PropOptions<T> still apply.

Anyone get this working in Storybook 7? Overriding the @vitejs/plugin-vue in Storybook's config breaks everything

Did you mean that it breaks the app with a postcss unexpected token error？

When adding

vue({
  script: {
    defineModel: true,
    propsDestructure: true,
  },
})

to Storybook's viteFinal config I get the following on boot:
[vite] Internal server error: At least one <template> or <script> is required in a single file component.

I went to use it at my own risk. I hope it becomes official too.
It is constructive when you define a custom component to be used multiple times. It saves much effort and time and prevents redundant code.

I also opened a PR in my company Repo, but we want to merge it if it gets out of experimental
But the PR is already working find 👌
Around 50 files affected

One more shoutout, found this incredibly convenient!

This doesn't work. Vue wont allow you to bind a value in a v-for.

<SchemaCollectionProvider v-for="schema in schemas" v-model:schema="schema" :key="schema.id">

throws: Internal server error: v-model cannot be used on v-for or v-slot scope variables because they are not writable.

The problem is that you are mixing typing and definition of props. It could be possible to implement something like this:

defineProps<{
  prop1?: string,
  modelValue: string
}>({
  models: [ 'modelValue' ]
});

May use better keyword:

defineProps<{prop1:string,modelValue:string}>({mutable:['modelValue']})

You can still access them via the modelModifiers prop (currently needs to be declared separately):

const props = defineProps<{ modelModifiers: { trim?: true } }>()
const msg = defineModel<string>()

if (props.modelModifiers.trim) {
  // ...
}

We can potentially make this automatically handled:

const msg = defineModel<string, { trim?: true }>()
//    ^ Ref<string | undefined> & { modifiers: { trim?: true }}

if (msg.modifiers.trim) {
  // ...
}

I think we will probably ship current defineModel as stable without this though, because:

1. This is currently not a blocking issue, and seems to be rarely used;
2. It can be provided as a follow-up to the current design, and it doesn't seem worth it to cause breaking changes to the current design.

Follow up on this: we have implemented modifiers support in the latest 3.4.0-rc.3 that doesn't change anything already discussed in this RFC:

const [msg, modifiers] = defineModel<string, 'trim' | 'capitalize'>()

if (modifiers.trim) {
  // ...
}

if (modifiers.capitalize) {
  // ...
}

// type error!
if (modifiers.foo) {}

The returned ref implements Symbol.iterator to support the array destructure.

Also implemented get & set transformers so the value conversion can be done without the need for an extra computed wrapper:

const [msg, modifiers] = defineModel<string>({
  set(value) {
    if (modifiers.trim) {
      value = value.trim()
    }
    if (modifiers.capitalize) {
      value = capitalize(value)
    }
    return value
  }
})

@yyx990803 I think it's better to pass the modifiers to the get/set callbacks as second argument:

const msg = defineModel<string>({
  set(value, modifiers) {
    if (modifiers.trim) {
      value = value.trim()
    }
    if (modifiers.capitalize) {
      value = capitalize(value)
    }
    return value
  }
})

While passing modifiers to get and set looks more encapsulated, avoids captures, and pollutes the global scope less, there are advantages to having them available globally.

You can change the behavior of your component based on modifiers, or react to the modifiers changing.
For example you couldn't create a .debounced modifier inside set().

Maybe having both (globally available + passed to get/set as second parameter) would be a nice compromise.

You could do schema, schemaIndex in schemas and then schemas[schemaIndex]

See vuejs/core#9598.

When trying to address these issues, I realized the previous behavioral difference between local vs. non-local mode is kinda pointless (and in fact, brings about unnecessary confusion).

When local is false and the parent doesn't use v-model on the child, the child ref value will always be undefined, making it useless. If the user declared the model with required: true, there would already be a warning about missing modelValue.

In vuejs/core@f74785b I've removed the local option, making the model automatically adapt based on whether the parent provides v-model or not:

• If the parent provides the necessary v-model prop, the child ref value will always be in sync with parent prop value.
• Otherwise, the child ref will behave like a normal local ref.

After the commit, Problems (1) and (3) are solved. Behavior difference in (2) still exists, but is no longer determined by the local option - instead, it depends on whether the parent provided the v-model props, which I think is reasonable.

defineModel('foo', { type: Number })

When you use the component you can't do that with regular v-model directive, instead you need to handle the event and prop yourself:

<MyComponent :modelValue="modelValue" @update:modelValue="modelValueHandler">

The modelValueHandler function should look like:

function modelValueHandler(newValue, oldValue) {
    // handle modelValue change
}

Question as someone who likes the 2 way data flow and wants it to be this easy: What is the best practice for this?

I really like mutable props (and basically use defineModel exactly for this).

It makes a lot of sense on dynamic components that take in some sort of an object that you want to edit it with. Like forms and what not. Otherwise it's always felt over-complicated. Just pass in 1 variable that can be edited and be done with it. I don't want to manage all the events and what not.