跳到內容
開始使用

圖示按鈕

動作 Icon Button

圖示按鈕是只有一個圖示、沒有文字的圓形按鈕,用在大家一看就懂的動作,例如返回、展開、搜尋、開啟選單,常放在導覽列、工具列這類空間很小的地方。淡底(tonal)是一般用法,實心(filled)用來強調;有 48px 和 64px 兩種大小。如果動作需要用文字才說得清楚,或是畫面上最重要的動作(例如送出、捐款),請改用有文字的「按鈕」。

部位說明
圓形容器按鈕的底色。淡底按鈕用淡淡的品牌底色,實心按鈕用主色;大小有 48px 和 64px 兩種。
圖示必填。放在圓形中間的一個圖示,顏色跟著變體:淡底按鈕是主色圖示,實心按鈕的圖示用和主色對比清楚的顏色。
標籤必填,但畫面上看不到。用一句話說出按下去會做什麼,例如「返回上一頁」;螢幕閱讀器會唸這段文字。
焦點框用鍵盤選到按鈕時出現的外框,讓不用滑鼠的人知道目前在哪裡。
停用狀態暫時不能按時整顆變淡。
類型 說明
建議 只用大家一看就懂的圖示,例如返回箭頭、放大鏡、三條線的選單。不確定讀者看不看得懂時,改用有文字的「按鈕」。
建議 每個圖示按鈕都要寫標籤,說出按下去會做什麼,例如「返回上一頁」「搜尋」。畫面上看不到,但螢幕閱讀器會唸出來。
建議 同一排的圖示按鈕用同一個大小;需要特別強調的那一個才用實心,其他用淡底。
避免 不要把畫面上最重要的動作(例如送出、立即捐款)只做成圖示按鈕;請用有文字的「按鈕」。
避免 不要在一個圖示按鈕裡放兩個圖示或加上文字。圓形裡只放得下一個圖示,需要文字時請用「按鈕」。

目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題

  • 預設變體: 用元件本身的預設變體。
  • 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
  • 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
  • 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、主色(滑鼠移上時;連結文字也用它)、品牌底色(襯在內容後的品牌色塊)、品牌底色(滑鼠移上時)、主色上的文字、焦點框(用鍵盤選到時的外框)。其餘和預設主題一樣。 看完整的顏色對照

上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變;這個元件還沒有淺色、深色並排的範例。

以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。

Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-icon-button> 的頁面;這一段的範例和 API 表就是它的說明。

<tc-icon-button> 是以圓形容器包裹單一圖示的按鈕,提供 tonal / filled 兩種變體與 md(48px)/ lg(64px)兩種尺寸。label 為必填,會套用至內部 <button> 的 aria-label。下方為可互動的真實元件:

<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" />
<script type="module" src="@tzuchi/components/cdn"></script>
<tc-icon-button variant="tonal" label="返回">
<tc-icon name="arrow-left"></tc-icon>
</tc-icon-button>
import { TcIconButton } from '@tzuchi/react';
<TcIconButton variant="filled" size="lg" label="向下展開" onClick={handleExpand}>
<TcIcon name="arrow-down" />
</TcIconButton>;
  • variant="tonal"(預設):品牌淺色底 + 品牌主色圖示。
  • variant="filled":品牌主色底 + 對比文字色圖示。
  • size="md"(預設,48px)/ size="lg"(64px),對應 --tc-size-control-*。

下表自 Custom Elements Manifest 自動產生:

Attribute Type Default Description
variant 'tonal' | 'filled' 'tonal'
size 'md' | 'lg' 'md'
disabled boolean false
label string '' 無障礙標籤,套用至內部 <button> 的 aria-label(必填)。
  • label 為必填,會套用至內部原生 <button> 的 aria-label,供螢幕報讀器辨識。
  • 內含原生 <button>,支援鍵盤 Enter / Space。
  • :focus-visible 焦點環使用 --tc-focus-ring-* token。
  • disabled 透過停用內部的原生控制項實作(非 pointer-events:none)。