WebberUI

Live Preview Wizard

左欄分步表單、右欄即時預覽畫布的雙欄 onboarding 版面;輸入即時 morph 反映到預覽,步驟切換時表單方向滑動、預覽交叉淡變。

載入預覽⋯

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

<LivePreviewWizard />

安裝

npx shadcn@latest add https://webberui.com/r/live-preview-wizard.json

或在 components.json 設定 registries 後,改用 @webberui/live-preview-wizard 安裝。

安裝依賴後,從 registry JSON(/r/live-preview-wizard.jsonfiles[0].content)複製 live-preview-wizard.tsx 原始碼到你的 components/ui/ 目錄:

npm install motion lucide-react clsx tailwind-merge

使用

<LivePreviewWizardStep> 宣告每一步的表單欄位,preview 提供右欄的即時預覽。步驟內的欄位透過 useLivePreviewWizard 讀寫共享的 values,輸入會即時反映到預覽。

import {
  LivePreviewWizard,
  LivePreviewWizardStep,
  useLivePreviewWizard,
} from "@/components/ui/live-preview-wizard";

type Form = {
  name: string;
};

function NameField() {
  const { values, setValue } = useLivePreviewWizard<Form>();
  return (
    <input
      value={values.name}
      onChange={(e) => setValue("name", e.target.value)}
    />
  );
}

function Preview() {
  const { values } = useLivePreviewWizard<Form>();
  return <h1>{values.name || "你的產品"}</h1>;
}

export function Example() {
  return (
    <LivePreviewWizard<Form>
      defaultValues={{ name: "" }}
      preview={<Preview />}
      onComplete={(values) => console.log(values)}
    >
      <LivePreviewWizardStep label="品牌">
        <NameField />
      </LivePreviewWizardStep>
    </LivePreviewWizard>
  );
}

Props

LivePreviewWizard

Prop型別預設值說明
childrenReactNode步驟宣告,皆為 <LivePreviewWizardStep>
previewReactNode | (ctx) => ReactNode預設的即時預覽內容;步驟未自訂時使用
valuesT受控表單資料;不傳則內部管理(非受控)
defaultValuesT{}非受控模式的初始資料
onValuesChange(values: T) => void資料變更時觸發,帶入最新完整資料
stepnumber受控目前步驟索引;不傳則內部管理
defaultStepnumber0非受控模式的初始步驟
onStepChange(step, direction) => void步驟變更時觸發(direction:1 前進、-1 後退)
onComplete(values: T) => void最後一步按「完成」時觸發
progress"dots" | "bar" | false"dots"進度指示款式;false 不顯示
controlsbooleantrue是否渲染內建的上一步/下一步控制列
previewSide"left" | "right""right"寬螢幕時預覽畫布置於哪一側
previewLabelstring"preview.app"預覽外框 faux 網址列文字
backLabel / nextLabel / completeLabelstring上一步 / 下一步 / 完成控制列按鈕文字
classNamestring追加到外層 grid 的樣式

LivePreviewWizardStep

Prop型別預設值說明
labelstring進度指示顯示的步驟標題
childrenReactNode本步驟的表單欄位
previewReactNode | (ctx) => ReactNode本步驟專屬預覽,覆寫容器的 preview
classNamestring追加到步驟容器的樣式

useLivePreviewWizard<T>()

回傳目前的 valuessetValue(key, value)setValues(partial),以及 steptotaldirectionisFirstisLastgoTonextback 等導覽狀態。需在 <LivePreviewWizard> 內呼叫。

細節

  • 雙模式valuesstep 皆支援受控(傳入 prop)與非受控(defaultValuesdefaultStep)兩種用法。
  • 即時 morph:欄位透過 setValue 寫入共享 values,同一步驟內預覽會即時重繪;顏色類變化建議搭配 CSS transition-colors 讓 morph 更平滑。
  • 方向感知nextbackgoTo 會推導切換方向,表單以水平滑動、預覽以交叉淡變過場。
  • 每步預覽:在 <LivePreviewWizardStep> 上設定 preview 可讓不同步驟強調不同重點,切換時自然交叉淡變。

可及性

  • 進度圓點/進度條帶 rolearia-*;已抵達的步驟可點擊跳轉,未抵達者停用。
  • 步驟區塊帶 aria-roledescription="步驟"aria-label,並以 aria-live="polite" 朗讀目前步驟。
  • 預覽畫布帶 aria-label="即時預覽";控制列按鈕皆可鍵盤操作並具 focus 樣式。
  • 使用者開啟「減少動態效果」時,滑動改為淡入淡出、彈簧過場停用,不影響版面結構。

On this page