Drawer

Sometimes, Dialog does not always satisfy our requirements, let's say you have a massive form, or you need space to display something like terms & conditions, Drawer has almost identical API with Dialog, but it introduces different user experience.

TIP

Since v-model is natively supported for all components, visible.sync has been deprecated, use v-model="visibilityBinding" to control the visibility of the current drawer.

Basic Usage

Callout a temporary drawer, from multiple direction

You must set model-value for Drawer like Dialog does to control the visibility of Drawer itself, it's boolean type. Drawer has three parts: title & body & footer, the title is a named slot, you can also set the title through attribute named title, default to an empty string, the body part is the main area of Drawer, which contains user defined content. When opening, Drawer expand itself from the right corner to left which size is 30% of the browser window by default. You can change that default behavior by setting direction and size attribute. This show case also demonstrated how to use the before-close API, check the Attribute section for more detail

left to rightright to lefttop to bottombottom to top

export function DrawerBasicUsage() {  const [direction, setDirection] = useState<DrawerDirection>("rtl");  const [visible, setVisible] = useState(false);  const [visible2, setVisible2] = useState(false);  const [radio, setRadio] = useState("Option 1");  return (    <>      <ElRadioGroup        value={direction}        onChange={(value) => setDirection(value as DrawerDirection)}      >        <ElRadio value="ltr">left to right</ElRadio>        <ElRadio value="rtl">right to left</ElRadio>        <ElRadio value="ttb">top to bottom</ElRadio>        <ElRadio value="btt">bottom to top</ElRadio>      </ElRadioGroup>      <ElButton type="primary" style={{ marginLeft: 28 }} onClick={() => setVisible(true)}>        open      </ElButton>      <ElButton type="primary" style={{ marginLeft: 16 }} onClick={() => setVisible2(true)}>        with footer      </ElButton>      <ElDrawer        visible={visible}        onVisibleChange={setVisible}        title="I am the title"        direction={direction}        beforeClose={(done) => {          MessageBox.confirm("Are you sure you want to close this?")            .then(() => done())            .catch(() => {});        }}      >        <span>Hi, there!</span>      </ElDrawer>      <ElDrawer        visible={visible2}        onVisibleChange={setVisible2}        direction={direction}        header={<h4 style={{ margin: 0 }}>set title by slot</h4>}        footer={          <div style={{ flex: "auto" }}>            <ElButton onClick={() => setVisible2(false)}>cancel</ElButton>            <ElButton              type="primary"              onClick={() => {                MessageBox.confirm(`Are you confirm to chose ${radio} ?`)                  .then(() => setVisible2(false))                  .catch(() => {});              }}            >              confirm            </ElButton>          </div>        }      >        <ElRadioGroup value={radio} onChange={(value) => setRadio(String(value))}>          <ElRadio value="Option 1" size="large">Option 1</ElRadio>          <ElRadio value="Option 2" size="large">Option 2</ElRadio>        </ElRadioGroup>      </ElDrawer>    </>  );}

No Title

When you no longer need a title, you can remove it from the drawer.

Set the withHeader attribute to false, you can remove the title from drawer, thus your drawer can have more space on screen. If you want to be accessible, make sure to set the title attribute.

export function DrawerNoTitle() {  const [visible, setVisible] = useState(false);  return (    <>      <ElButton type="primary" onClick={() => setVisible(true)}>        open      </ElButton>      <ElDrawer        visible={visible}        onVisibleChange={setVisible}        title="I am the title"        withHeader={false}      >        <span>Hi there!</span>      </ElDrawer>    </>  );}

Customized Content

Like Dialog, Drawer can be used to display a multitude of diverse interactions.

export function DrawerCustomizationContent() {  const [tableVisible, setTableVisible] = useState(false);  const [formVisible, setFormVisible] = useState(false);  const [form, setForm] = useState({ name: "", region: "" });  const [loading, setLoading] = useState(false);  const submit = () => {    setLoading(true);    setTimeout(() => {      setLoading(false);      setFormVisible(false);    }, 400);  };  return (    <>      <ElButton text onClick={() => setTableVisible(true)}>        Open Drawer with nested table      </ElButton>      <ElButton text onClick={() => setFormVisible(true)}>        Open Drawer with nested form      </ElButton>      <ElDrawer        visible={tableVisible}        onVisibleChange={setTableVisible}        title="I have a nested table inside!"        direction="rtl"        size="50%"      >        <ElTable data={gridData}>          <ElTableColumn property="date" label="Date" width={150} />          <ElTableColumn property="name" label="Name" width={200} />          <ElTableColumn property="address" label="Address" />        </ElTable>      </ElDrawer>      <ElDrawer        visible={formVisible}        onVisibleChange={setFormVisible}        title="I have a nested form inside!"        direction="ltr"        className="demo-drawer"        beforeClose={(done) => {          if (loading) return;          MessageBox.confirm("Do you want to submit?")            .then(() => {              setLoading(true);              setTimeout(() => {                done();                setTimeout(() => setLoading(false), 400);              }, 2000);            })            .catch(() => {});        }}      >        <div style={{ display: "grid", gap: "0.875rem" }}>          <label style={{ display: "flex", alignItems: "center", gap: "0.5rem" }}>            <span style={{ width: 80 }}>Name</span>            <ElInput              value={form.name}              onChange={(value) => setForm((current) => ({ ...current, name: value }))}            />          </label>          <label style={{ display: "flex", alignItems: "center", gap: "0.5rem" }}>            <span style={{ width: 80 }}>Area</span>            <ElSelect              value={form.region}              onChange={(value) =>                setForm((current) => ({ ...current, region: String(value ?? "") }))              }              placeholder="Please select activity area"              options={[                { value: "shanghai", label: "Area1" },                { value: "beijing", label: "Area2" },              ]}              style={{ flex: 1 }}            />          </label>        </div>        <div style={{ marginTop: "1.25rem", display: "flex", gap: "0.75rem" }}>          <ElButton            onClick={() => {              setLoading(false);              setFormVisible(false);            }}          >            Cancel          </ElButton>          <ElButton type="primary" loading={loading} onClick={submit}>            {loading ? "Submitting ..." : "Submit"}          </ElButton>        </div>      </ElDrawer>    </>  );}

Customized Header

The header slot can be used to customize the area where the title is displayed. In order to maintain accessibility, use the title attribute in addition to using this slot, or use the titleId slot property to specify which element should be read out as the drawer title.

export function DrawerCustomizationHeader() {  const [visible, setVisible] = useState(false);  return (    <>      <ElButton onClick={() => setVisible(true)}>        Open Drawer with customized header      </ElButton>      <ElDrawer        visible={visible}        onVisibleChange={setVisible}        showClose={false}        header={({ close, titleId, titleClass }) => (          <div            style={{              display: "flex",              alignItems: "center",              justifyContent: "space-between",              gap: 16,              width: "100%",            }}          >            <h4 id={titleId} className={titleClass} style={{ margin: 0 }}>              This is a custom header!            </h4>            <ElButton type="danger" onClick={close}>              <CircleCloseFilled style={{ marginRight: 4 }} />              Close            </ElButton>          </div>        )}      >        This is drawer content.      </ElDrawer>    </>  );}

Resizable Drawer 2.11.0

Try to drag the edge part.

Set resizable to true to resize.

toprightbottomleft

export function DrawerResizable() {  const [direction, setDirection] = useState<DrawerDirection>();  const [visible, setVisible] = useState(false);  return (    <>      <ElRadioGroup        value={direction}        onChange={(value) => {          setDirection(value as DrawerDirection);          setVisible(true);        }}      >        <ElRadio value="ttb" button>top</ElRadio>        <ElRadio value="rtl" button>right</ElRadio>        <ElRadio value="btt" button>bottom</ElRadio>        <ElRadio value="ltr" button>left</ElRadio>      </ElRadioGroup>      <ElDrawer        visible={visible}        onVisibleChange={setVisible}        direction={direction}        resizable      >        This is drawer content.      </ElDrawer>    </>  );}

Nested Drawer

You can also have multiple layer of Drawer just like Dialog.

If you need multiple Drawer in different layer, you must set the append-to-body attribute to true

export function DrawerNestedDrawer() {  const [visible, setVisible] = useState(false);  const [innerVisible, setInnerVisible] = useState(false);  return (    <>      <ElButton type="primary" onClick={() => setVisible(true)}>        open      </ElButton>      <ElDrawer        visible={visible}        onVisibleChange={setVisible}        title="I'm outer Drawer"        size="50%"      >        <div>          <ElButton onClick={() => setInnerVisible(true)}>Click me!</ElButton>          <ElDrawer            visible={innerVisible}            onVisibleChange={setInnerVisible}            title="I'm inner Drawer"            appendToBody            beforeClose={(done) => {              MessageBox.confirm("You still have unsaved data, proceed?")                .then(() => done())                .catch(() => {});            }}          >            <p>_(:зゝ∠)_</p>          </ElDrawer>        </div>      </ElDrawer>    </>  );}

Setting modal to false will hide modal (overlay) of drawer.

Starting from version 2.11.7, modal-penetrable attribute is added, which can be penetrable.

export function DrawerModal() {  const [visible, setVisible] = useState(false);  return (    <>      <ElButton plain onClick={() => setVisible(true)}>        Open the modal Drawer      </ElButton>      <ElDrawer        visible={visible}        onVisibleChange={setVisible}        modal={false}        modalPenetrable        footer={          <div style={{ display: "flex", justifyContent: "flex-end", gap: "0.75rem" }}>            <ElButton onClick={() => setVisible(false)}>Cancel</ElButton>            <ElButton type="primary" onClick={() => setVisible(false)}>              Confirm            </ElButton>          </div>        }      >        <span>It&apos;s a modal Drawer</span>      </ElDrawer>    </>  );}

TIP

The content inside Drawer should be lazy rendered, which means that the content inside Drawer will not impact the initial render performance, therefore any DOM operation should be performed through ref or after open event emitted.

TIP

Drawer provides an API called destroy-on-close, which is a flag variable that indicates should destroy the children content inside Drawer after Drawer was closed. You can use this API when you need your mounted life cycle to be called every time the Drawer opens.

API

Attributes

Name	Description	Type	Default
model-value / v-model	Should Drawer be displayed	`boolean`	false
append-to-body	Controls should Drawer be inserted to DocumentBody Element, nested Drawer must assign this param to true	`boolean`	false
append-to 2.8.0	which element the Drawer appends to. Will override `append-to-body`	`CSSSelector` / `HTMLElement`	body
lock-scroll	whether scroll of body is disabled while Drawer is displayed	`boolean`	true
before-close	If set, closing procedure will be halted	`Function`	—
close-on-click-modal	whether the Drawer can be closed by clicking the mask	`boolean`	true
close-on-press-escape	Indicates whether Drawer can be closed by pressing ESC	`boolean`	true
open-delay	Time(milliseconds) before open	`number`	0
close-delay	Time(milliseconds) before close	`number`	0
destroy-on-close	Indicates whether children should be destroyed after Drawer closed	`boolean`	false
modal	Should show shadowing layer	`boolean`	true
modal-penetrable 2.11.7	whether the mask is penetrable. The modal attribute must be `false`.	`boolean`	false
direction	Drawer's opening direction	`enum`	rtl
resizable 2.11.0	enable resizable feature for Drawer	`boolean`	false
show-close	Should show close button at the top right of Drawer	`boolean`	true
size	Drawer's size, if Drawer is horizontal mode, it effects the width property, otherwise it effects the height property, when size is `number` type, it describes the size by unit of pixels; when size is `string` type, it should be used with `x%` notation, other wise it will be interpreted to pixel unit	`number` / `string`	30%
title	Drawer's title, can also be set by named slot, detailed descriptions can be found in the slot form	`string`	—
with-header	Flag that controls the header section's existence, default to true, when withHeader set to false, both `title attribute` and `title slot` won't work	`boolean`	true
modal-class	Extra class names for shadowing layer	`string`	—
header-class 2.9.3	custom class names for header wrapper	`string`	—
body-class 2.9.3	custom class names for body wrapper	`string`	—
footer-class 2.9.3	custom class names for footer wrapper	`string`	—
z-index	set z-index	`number`	—
header-aria-level a11y	header's `aria-level` attribute	`string`	2
custom-class deprecated	Extra class names for Drawer	`string`	—

WARNING

custom-class has been deprecated, and will be removed in 2.3.0, please use class.

Events

Name	Description	Type
open	Triggered before Drawer opening animation begins	`Function`
opened	Triggered after Drawer opening animation ended	`Function`
close	Triggered before Drawer closing animation begins	`Function`
closed	Triggered after Drawer closing animation ended	`Function`
open-auto-focus	triggers after Drawer opens and content focused	`Function`
close-auto-focus	triggers after Drawer closed and content focused	`Function`
resize-start 2.11.8	Triggered when resizing starts (when `resizable` is enabled)	`Function`
resize 2.11.8	Triggered while resizing (when `resizable` is enabled)	`Function`
resize-end 2.11.8	Triggered when resizing ends (when `resizable` is enabled)	`Function`

Slots

Name	Description
default	Drawer's Content
header	Drawer header section; Replacing this removes the title, but does not remove the close button.
footer	Drawer footer Section
title deprecated	Works the same as the header slot. Use that instead.

WARNING

title has been deprecated, and will be removed in 3.0.0, please use header.

Exposes

Name	Description
handleClose	In order to close Drawer, this method will call `before-close`.