Design SystemComponentsModal

Modal

Installation

import { Modal } from "@olab/components";

Overview

置中的對話框：背景蓋一層模糊暗幕，面板預設寬 480px（最寬 90% 螢幕），20px 圓角、內距 20px。可以有標題，右上角預設有關閉鈕。

點暗幕、按 ESC 或按關閉鈕都會關閉；closable=false 時只能靠面板裡的按鈕關閉。打開時頁面不能捲動。

Interactive Demo

OPEN — backdrop + portal dialog

State Matrix

PANEL — static replica (same classes, rendered in place; backdrop omitted)

Dialog Title

With title and close button.
title · closable
Without title.
no title

Not closable

No close button; backdrop click is ignored.
closable = false

Dialog Title

Close button hover.
close · hover (sim)

Examples

WITHOUT TITLE — title omitted, close icon still shown

closable=false — only inner actions close it

Spec

PartValueSource class
Backdrop暗幕 + 輕度模糊bg-dark-8 backdrop-blur-xs
Panel寬 480px（預設，最寬 90vw），20px 圓角，內距 20pxrounded-2xl border p-5 · width 480px
Panel border1pxborder-secondary
TitleText（16px），主要文字Text text-primary
Close button右上各 12px，內距 4px，圓角 4pxabsolute top-3 right-3 p-1 rounded
Close button · hover淡底hover:bg-secondary
Layer蓋在所有內容之上，打開時頁面不能捲動z-[9999] · preventScroll

數值為 2026-06-11 在 dark 模式下的實測（getComputedStyle）；source class 對照目前的元件原始碼，色票隨目前的 dark / light 模式即時解析。完整量測、狀態細節與已知不一致見 live-ds-spec/modal.md。

Usage

Do

  • 需要使用者停下來專心處理的事：確認下單、送出 dispute、重要警告。
  • 按鈕放在右下角，主要動作在最右邊（Cancel、Confirm）。
  • 只有在使用者必須做出選擇時才關掉 closable。

Don't

  • 不要拿 Modal 顯示可以放在頁面上的資訊；能不打斷就不打斷。
  • 不要在 Modal 裡再開另一個 Modal。
  • 不要用 className 改圓角或內距；浮層外觀應該跟 Popover、Toast 一致。