---
title: "DrawerForm"
description: "A form in a side drawer for creating or editing records."
category: Form
status: beta
since: 0.9.2
tags: [form, drawer, panel]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
A drawer keeps the page in view for longer forms; each open edits a copy of `initialValues`, and the drawer closes once the submit succeeds.
::::TuffDemoWrapper{demo="DrawerFormBasicDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const open = ref(false)
  const projects = ref([])
  // Every open starts from these
  const blank = { name: '', key: '', description: '', visibility: 'team' }
  const rules = {
    name: { required: true, message: 'Enter a project name' },
    key: { pattern: /^[A-Z][A-Z0-9]{1,9}$/, message: 'Use 2 to 10 capital letters or digits, starting with a letter' },
  }

  async function create(values) {
    const project = await createProject(values)
    projects.value = [project, ...projects.value]
  }
  </script>

  <template>
    <TxButton variant="primary" @click="open = true">New project</TxButton>
    <TxDrawerForm
      v-model:visible="open"
      title="New project"
      :initial-values="blank"
      :rules="rules"
      :drawer-props="{ size: 'min(92vw, 440px)' }"
      layout="stacked"
      submit-text="Create"
      @submit="create"
    >
      <template #default="{ model }">
        <TxFormItem label="Name" prop="name">
          <TuffInput v-model="model.name" />
        </TxFormItem>
        <TxFormItem label="Key" prop="key" help="2 to 10 capital letters or digits, starting with a letter" width="sm">
          <TuffInput v-model="model.key" />
        </TxFormItem>
        <TxFormItem label="Description" prop="description">
          <TxTextarea v-model="model.description" :rows="3" resize="none" />
        </TxFormItem>
        <TxFormItem label="Visibility" prop="visibility">
          <TxRadioGroup v-model="model.visibility" type="standard" direction="row">
            <TxRadio value="private" label="Only me" />
            <TxRadio value="team" label="Team" />
            <TxRadio value="public" label="Public" />
          </TxRadioGroup>
        </TxFormItem>
      </template>
    </TxDrawerForm>
  </template>
---
::::

### Loading After Opening
Open the drawer first, and hand the record to `initialValues` once it arrives; it becomes the saved state, and fields the user has already changed keep their edits.

```vue
<script setup lang="ts">
const open = ref(false)
const project = ref()

async function edit(id) {
  project.value = undefined
  open.value = true
  project.value = await fetchProject(id)
}
</script>

<template>
  <TxDrawerForm v-model:visible="open" title="Edit project" :initial-values="project" :disabled="!project" @submit="save">
    <template #default="{ model }">…</template>
  </TxDrawerForm>
</template>
```

### Best Practices

- Use it for forms with many fields, forms that scroll, or forms read against the page. For a few fields, use `TxModalForm`.
- Set the drawer's width in `drawerProps.size`. The form's own `size` sizes its controls.
- Drawer forms do not autosave. To save as the user edits, put a `TxForm` with `autosave` in a `TxDrawer`.
- Return a promise from `@submit`. Return `false`, throw, or call `setErrors()`, and the drawer stays open.
- Outside English, pass `submitText`, `cancelText`, `messages.leaveConfirm`, and `drawerProps.closeLabel` to name the close button.

## API Reference

### Props

The `TxForm` props below apply too: the drawer builds `model` from `initialValues`, and `autosave` does not apply.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | required | Shows the drawer. Use with `v-model:visible`. |
| `title` | `string` | `''` | Drawer title. |
| `initialValues` | `FormValues` | - | The values the form opens with. Each open edits a copy, so the parent's values change only when the parent changes them. |
| `submitText` | `string` | `'Save'` | Text of the submit button. |
| `cancelText` | `string` | `'Cancel'` | Text of the cancel button. |
| `drawerProps` | `Record<string, unknown>` | - | Any other `TxDrawer` prop, such as `size` or `direction`. Closing is asked of the form, not of `beforeClose`. |
| `id` | `string` | generated | The form's id, and the prefix of every field id. |
| `rules` | `FormRules` | - | Form-level rules keyed by field path. |
| `schema` | `FormStandardSchema` | - | A Standard Schema v1 validator checked against the whole `model`; issues with no matching field are listed in the error summary. |
| `layout` | `'auto' \| 'side' \| 'stacked' \| 'inline'` | `'auto'` | Field layout. |
| `labelPosition` | `'left' \| 'right' \| 'top'` | - | Older spelling of `layout`. |
| `labelAlign` | `'start' \| 'end'` | `'end'` | Label alignment in the side column. |
| `labelWidth` | `string \| number` | `16em` | Widest the side label column may grow; numbers are in pixels. |
| `requiredMark` | `'asterisk' \| 'optional' \| 'none'` | `'asterisk'` | Marks required fields with an asterisk, optional fields with `messages.optional`, or neither. |
| `validateOn` | `'blur' \| 'submit'` | `'blur'` | When the first message appears: on leaving a changed field, or on the first submit. |
| `messages` | `Partial<FormMessages>` | - | Overrides the built-in text. |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size of the controls inside; the drawer width is `drawerProps.size`. |
| `disabled` | `boolean` | `false` | Disables the controls inside that read the form, and blocks submit. |
| `readonly` | `boolean` | `false` | Shows the values as a record: controls can be focused and copied, not changed; no field is marked required. |
| `reconcile` | `FormReconcile` | - | Decides what `model` holds when fetched values reach fields the user changed. |
| `persist` | `boolean \| FormPersistOptions` | `false` | Keeps what the user typed under `id`; `true` takes the defaults. |
| `leaveConfirm` | `FormLeaveConfirm \| false` | host's, then `window.confirm` | Asked before leaving with changes no draft holds; `false` never asks. |
| `onSubmit` | `(values: FormValues, event?: Event) => unknown` | - | Called once every check passes; the drawer stays open until a returned promise settles. `@submit` binds it. |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:visible` | `(value: boolean)` | The drawer opens or closes. |
| `submit-success` | `(values: FormValues)` | The submit went through; the drawer closes next. |
| `validate` | `(valid: boolean)` | As on `TxForm`. |
| `persist-error` | `(error: unknown)` | As on `TxForm`. |

### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `default` | `{ model, dirty, valid, submitting, submitted, errors, rootError }` | The form items. `model` is the copy this open edits. |
| `footer` | `{ formId, submitting, cancel }` | Replaces the cancel and submit buttons. Point the submit button at the form with `:form="formId"`. |

### Exposed Methods

| Name | Type | Description |
|------|------|-------------|
| `form` | `TxForm \| null` | The form inside, with every `TxForm` method; `null` until the drawer first opens. |
| `cancel` | `() => Promise<void>` | Closes as Cancel does: the form first asks about changes it would lose. |

## Overview

- Each open builds `model` from a copy of `initialValues` and makes it the baseline, so edits left at closing never carry over to the next open.
- When `initialValues` changes while the drawer is open, it becomes the saved state: untouched fields take the new values, and fields the user changed keep their edits.
- Escape, the mask, the close button and Cancel all go through the form's `confirmLeave()`, which asks only about changes no draft holds. A running submit cannot be closed.
- Escape with focus inside a `TxForm` does not reach this path (see the Drawer focus rule), so it asks nothing.
- After its first open the drawer keeps its content, and the form with it. Closed, it has nothing left to lose, so reloading the page does not ask.
- A submit that goes through emits `submit-success`, then closes.

## Technologies

- Built from `TxDrawer` and `TxForm`, with `beforeClose` wired to the form's `confirmLeave()`. Opening, copying and closing share `form/src/use-overlay-form.ts` with `TxModalForm`.
- The footer sits outside the `<form>`, and the submit button reaches it through `form`: Enter in a field and a click make the same submit.
- Source: `packages/tuffex/packages/components/src/drawer-form/`.

<TuffDocSourceLink />
