Toggle

눌린 채로 머무는 버튼입니다. 액션을 실행하지 않고 상태를 유지합니다. 선택한 글자의 굵기, 캔버스의 격자, 목록에 걸린 필터가 그런 상태입니다.

import { Toggle } from 'neba';

<Toggle defaultPressed>Bold</Toggle>;

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'outline' | 'text'	'outline'	토글이 **꺼져 있을 때**의 표면 무게. 켜졌을 때는 어느 weight든 색 계열이 전면에 나섭니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	높이와 타입 스케일
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	켜졌을 때 띠는 의미론적 색 역할. 꺼져 있으면 어느 계열이든 중립입니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
pressed	boolean	—	켜져 있는지 여부. onPressedChange와 함께 쓰면 controlled 컴포넌트가 됩니다
defaultPressed	boolean	false	처음에 켜진 채로 시작할지 여부 (uncontrolled)
onPressedChange	(pressed: boolean) => void	—	상태가 바뀔 때마다 호출됩니다
value	string	—	ToggleGroup 안에서 이 토글을 식별하는 값
startIcon	ReactNode	—	라벨 앞의 내용. em 단위라 라벨을 따라갑니다
endIcon	ReactNode	—	라벨 뒤의 내용
disabled	boolean	false	사용 불가. 색 계열을 버리고 중립 회색이 됩니다
fullWidth	boolean	false	컨테이너 너비만큼 확장합니다
children	ReactNode	—	라벨. 없으면 아이콘을 감싸는 정사각형이 되며, 이때는 aria-label이 필요합니다

<button>의 모든 속성이 그대로 전달됩니다. 예외는 ToggleGroup 안에서 토글을 식별하는 value와 의미론적 색 역할인 color뿐입니다. 공통 축은 prop 규칙에 정리되어 있습니다.

Switch는 설정을 바꾸고 그 변화 자체가 목적이며, Checkbox는 폼과 함께 제출되는 답변입니다. Toggle은 둘 다 아닙니다. 옆에 있는 대상에 작용하는 컨트롤입니다.

예시

pressed와 onPressedChange

pressed와 onPressedChange로 controlled, defaultPressed로 uncontrolled 컴포넌트가 됩니다.

import { useState } from 'react';
import { Toggle } from 'neba';

export default function ToggleControlled() {
  const [grid, setGrid] = useState(true);

  return (
    <div className="flex flex-col items-center gap-4">
      <Toggle pressed={grid} onPressedChange={setGrid}>
        Grid
      </Toggle>

      <div
        className="size-40 rounded-(--neba-radius-md) border border-(--neba-line)"
        style={{
          backgroundImage: grid
            ? 'linear-gradient(var(--neba-line) 1px, transparent 1px), linear-gradient(90deg, var(--neba-line) 1px, transparent 1px)'
            : undefined,
          backgroundSize: '16px 16px'
        }}
      />
    </div>
  );
}

variant

variant는 토글이 꺼져 있을 때의 모습을 정합니다. outline이 기본이고, solid는 켜지면 accent로 채워지는 판이며, text는 hover하거나 켜지기 전까지 표면이 전혀 없습니다.

꺼진 토글은 세 variant 어디에서도 색 계열을 띠지 않습니다. 판은 중립 회백색이고 글자는 muted이며, 켜지는 순간 판과 글자와 hairline이 한꺼번에 accent로 넘어갑니다.

import { Toggle } from 'neba';

const variants = ['solid', 'outline', 'text'] as const;

export default function ToggleVariants() {
  return (
    <div className="flex flex-col gap-4">
      {variants.map((variant) => (
        <div key={variant} className="flex items-center gap-3">
          <span className="w-16 text-[0.75rem] text-(--neba-muted-fg)">{variant}</span>
          <Toggle variant={variant}>Off</Toggle>
          <Toggle variant={variant} defaultPressed>
            On
          </Toggle>
          <Toggle variant={variant} disabled>
            Disabled
          </Toggle>
        </div>
      ))}
    </div>
  );
}

아이콘만 있는 토글

children이 없으면 토글은 startIcon을 감싸는 정사각형이 됩니다. 툴바가 원하는 모양입니다. 아이콘은 접근 가능한 이름을 만들지 못하므로 aria-label을 주세요.

import { Toggle } from 'neba';

function BoldIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M4.5 3h4a2.5 2.5 0 0 1 0 5h-4V3Zm0 5h4.5a2.5 2.5 0 0 1 0 5H4.5V8Z"
        stroke="currentColor"
        strokeWidth="1.6"
        strokeLinejoin="round"
      />
    </svg>
  );
}

function ItalicIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path d="M10 3H6.5m3 10H6m3.5-10L7 13" stroke="currentColor" strokeWidth="1.6" />
    </svg>
  );
}

function UnderlineIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M4.5 2.5v5a3.5 3.5 0 0 0 7 0v-5M3.5 14h9"
        stroke="currentColor"
        strokeWidth="1.6"
        strokeLinecap="round"
      />
    </svg>
  );
}

export default function ToggleIcons() {
  return (
    <div className="flex items-center gap-2">
      <Toggle variant="text" aria-label="Bold" defaultPressed startIcon={<BoldIcon />} />
      <Toggle variant="text" aria-label="Italic" startIcon={<ItalicIcon />} />
      <Toggle variant="text" aria-label="Underline" startIcon={<UnderlineIcon />} />
    </div>
  );
}

size

size는 Button·TextField·Chip이 쓰는 것과 같은 컨트롤 높이입니다. 여러 컨트롤이 섞인 행에서도 baseline이 유지됩니다.

import { Toggle } from 'neba';

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function ToggleSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {sizes.map((size) => (
        <Toggle key={size} size={size} defaultPressed>
          {size}
        </Toggle>
      ))}
    </div>
  );
}

color

color는 토글이 켜졌을 때 띠는 색입니다. 꺼져 있으면 어느 계열이든 중립입니다.

import { Toggle } from 'neba';

const colors = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;

export default function ToggleColors() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {colors.map((color) => (
        <Toggle key={color} color={color} defaultPressed>
          {color}
        </Toggle>
      ))}
    </div>
  );
}

접근성

• aria-pressed를 가진 <button>으로 렌더링됩니다.
• 아이콘만 있는 토글에는 aria-label이 필요합니다. 이름을 가져올 텍스트가 없습니다.
• ToggleGroup 안에서는 세트 전체가 하나의 tab stop이고, 방향키로 구성원 사이를 이동합니다.