How to bi-directionally sync an external ref with useForm?

[LcsGa]

In a large-scale application, I am using vee-validate to handle all forms, with valibot for the validation schemas.

I need to support two different form behaviors:

1. A standard form with a submit action (the default useForm approach).
   2.A form where the values are fully synchronized with an external reactive model (a ref).

I am struggling to find the best way to achieve this second pattern. Ideally, I would love to pass a ref directly to the form controller to drive its values, similar to:

const myModel = ref({ username: 'Lucas', newsletter: true });

const { ... } = useForm({
  model: myModel, // Direct bi-directional synchronization with a Vue ref
  validationSchema: schema
});

Where:

• If myModel changes externally, the form fields and their validation states update accordingly.
• If a form field value changes, myModel is updated instantly.

As far as I know, vee-validate does not natively support passing a ref to drive the whole form values this way (the state remains internal to vee-validate).

Coming from Angular, this mirrors how the new Signal Forms API works, and it is a workflow I find incredibly robust and convenient for managing forms.

Right now, the only options I see are:

• Moving away from vee-validate to use another form library.
• Writing a custom composable like a useSyncedForm from scratch to sync the vee-validate form instance with a ref.

Is there an idiomatic way or a specific pattern to achieve this bi-directional synchronization between an external ref and vee-validate's internal state without adding a lot of manual boilerplate?

[LcsGa]

To clear things up, I haven’t fully integrated useForm yet. I am an Angular developer building my first Vue 3 application (a chess side-project to help users practice and improve).

Architecturally, I have built my own internal Design System with components like UiFormField, UiLabel, UiInput, etc.

• UiFormField is a wrapper handling the consistent layout, icons, actions, and error rendering.
• It accepts either a name prop (triggering useField(() => name) internally) OR a standalone FieldContext directly via a field prop.

Because of this design, I need useForm to support two distinct workflows:

1. The Standard Way: The default behavior described in the documentation. I pass a validation schema and initialValues, then plug it into the template using handleSubmit and field names.
2. The "Reactive Model" Way (The reason for this post): Technically, I could bypass vee-validate entirely for this use case by wiring my fields with simple v-models. However, for global architectural consistency across my app, I want to use the same form components. Ideally, I would love to replace initialValues with a reactive ref. If that external ref changes, the form values update; if a form value changes, the external ref stays perfectly in sync.

To give you a real-world example of why this matters, let's look at chess.

In chess, game states are shared using a FEN string, which looks like this:
rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

• rnbqkbnr/... is the piece positioning on the board.
• w indicates whose turn it is (White).
• KQkq represents castling rights.
• - is the available en-passant square (currently none).
• 0 1 are the half-move and full-move clocks.

In my app, I have an /analysis-board page to analyze a position, and a /editor page to modify the board. To share positions seamlessly between these pages (and allow users to copy/paste the URL to friends), the URL query parameters act as the single source of truth.

I am using a custom composable that leverages VueUse’s useRouteQuery to parse and build this FEN reactively:

export function useFen(defaultFen: MaybeRefOrGetter<string> = FEN.start) {
  const fen = useRouteQuery<string>('fen', defaultFen);

  const fenGroups = computed(() => FEN_REGEX.exec(fen.value)?.groups);

  const turn = computed({
    get: () => fenGroups.value?.turn ?? 'w',
    set: (newTurn) =>
      (fen.value = fen.value.replace(FEN_REGEX, `$<board> ${newTurn} $<castle> $<enPassant> $<halfMove> $<fullMove>`)),
  });

  const castle = useCastle(fen, () => fenGroups.value?.castle);

  const enPassant = computed({
    get: () => fenGroups.value?.enPassant ?? '-',
    set: (newEnPassant) =>
      (fen.value = fen.value.replace(FEN_REGEX, `$<board> $<turn> $<castle> ${newEnPassant} $<halfMove> $<fullMove>`)),
  });

  const halfMove = computed({
    get: () => fenGroups.value?.halfMove ?? '0',
    set: (newHalfMove) =>
      (fen.value = fen.value.replace(FEN_REGEX, `$<board> $<turn> $<castle> $<enPassant> ${newHalfMove} $<fullMove>`)),
  });

  const fullMove = computed({
    get: () => fenGroups.value?.fullMove ?? '1',
    set: (newFullMove) =>
      (fen.value = fen.value.replace(FEN_REGEX, `$<board> $<turn> $<castle> $<enPassant> $<halfMove> ${newFullMove}`)),
  });

  return {
    value: fen,
    turn,
    castle,
    enPassant,
    halfMove,
    fullMove,
  };
}

In pages/editor.vue, I provide a board instance (provideChessBoardEditor) that uses this useFen composable under the hood. In the template, I need to map each reactive property (turn, castle, enPassant, etc.) to individual form fields.

• If the FEN in the URL (or in a dedicated <input>) changes, the form values must update.
• If the user moves a piece on the board, toggles a castling right checkbox or changes the turn via a dropdown, the FEN string updates, instantly mutating the URL.

Once the user is satisfied with the position they created or modified, they navigate back to the /analysis-board page while preserving the ?fen=... query parameter, seamlessly carrying over their custom position to the analysis tool.

Coming from Angular, the framework makes no distinction between a "traditional" form and a form bound to a reactive model (using Signals). You get a single, unifed API for both.

That is exactly what I am looking for here: a common, uniform pattern in Vue/vee-validate that handles both standard forms and model-driven/URL-driven forms seamlessly.

[LcsGa]

Someone already gave me a decent workaround, but I would really love to find a cleaner solution (ideally something like a custom function useSyncedForm<...>(model: Ref<T>, options: FormOptions<...>): FormContext<...> instead).

[LcsGa]

To better understand what I am looking for based on my Angular background, here is the official documentation on form models