입력 컴포넌트
Material Design 3 스펙에 맞춘 입력 컴포넌트들입니다. 텍스트 필드, 체크박스, 라디오 버튼, 스위치, 슬라이더를 제공합니다.
m3-text-field (텍스트 입력)
플로팅 라벨을 가진 텍스트 입력 필드입니다.
기본 사용법
소스 코드 보기
TIP
placeholder=" "(공백 한 칸)은 필수입니다. CSS의 :placeholder-shown 선택자로 라벨 플로팅을 구현하기 때문입니다.
상태 변형
소스 코드 보기
아이콘 포함
소스 코드 보기
색상 변형
소스 코드 보기
Supporting Text (보조 텍스트)
소스 코드 보기
Size 변형 (newtil 확장)
M3 스펙은 56dp 한 크기만 정의하지만, 데스크톱·dense UI 실전 요구로 size variant를 확장 제공합니다. field-size:xs/sm/md/lg/xl (별칭: field-size:1/2/3/4/5).
소스 코드 보기
| 클래스 | 별칭 | 높이 | 용도 |
|---|---|---|---|
field-size:xs | field-size:1 | 40dp | 매우 촘촘한 admin, 검색바 |
field-size:sm | field-size:2 | 48dp | admin 폼, 필터 |
field-size:md | field-size:3 | 56dp | M3 기본값 |
field-size:lg | field-size:4 | 64dp | 여유 있는 폼 |
field-size:xl | field-size:5 | 72dp | 히어로, 눈에 띄는 입력 |
접근성
xs, sm은 데스크톱·dense UI용입니다. 모바일 터치 맥락에선 WCAG 44dp 터치 타깃 기준 미달 가능성이 있으니, 외부 패딩으로 터치 영역을 보강하거나 더 큰 size를 사용하세요.
Label 위치 (newtil 확장)
M3 기본은 floating label(필드 내부에서 애니메이션으로 이동)이지만, dense 폼이나 긴 라벨, 가로 정렬 폼에서는 외부 라벨이 더 적합합니다. field-label:*로 전환합니다.
기본 (floating label, M3 스펙):
소스 코드 보기
외부 라벨 — 위 (field-label:top):
소스 코드 보기
외부 라벨 — 왼쪽 (field-label:left):
소스 코드 보기
외부 라벨 — 오른쪽 / 아래 / 없음:
소스 코드 보기
옵션 값 정리:
| 클래스 | label 위치 | placeholder 동작 | 용도 |
|---|---|---|---|
| (없음) | 필드 내부 floating | 포커스 시 표시 | M3 기본, 폼 전반 |
field-label:top | 필드 위 | 기본 표시 | 전통적 웹 폼 |
field-label:left | 필드 왼쪽 | 기본 표시 | 설정 페이지, 가로 정렬 폼 |
field-label:right | 필드 오른쪽 | 기본 표시 | 특수 레이아웃 |
field-label:bottom | 필드 아래 | 기본 표시 | 캡션 형태 힌트 |
field-label:none | 숨김 | 기본 표시 | 검색바, 인라인 입력 |
TIP
field-label:left/right는--field-label-min-width(기본 6rem)로 라벨 너비 조정 가능- 외부 모드에선 placeholder가 항상 보이므로 placeholder에 힌트 문구(예:
placeholder="예: ROLE_STUDENT")를 넣는 게 자연스럽습니다 - floating 모드 유지하면서 라벨 길이가 부담되면 힌트는 Supporting Text로 분리하세요
Variable API
| 변수 | 기본값 | 설명 |
|---|---|---|
--field-background | var(--color-surface-2) | 배경 색상 |
--field-border | none | 테두리 |
--field-border-radius | 0.25rem 0.25rem 0 0 | 모서리 둥글기 |
--field-padding-x | 1rem | 좌우 여백 |
--field-padding-top | 0.5rem | 상단 여백. 레이블이 상자 밖(field-label:top/bottom/left/right/none)이면 input 의 위·아래 패딩이 모두 이 값을 따른다 |
--field-padding-bottom | 0.5rem | 하단 여백 (떠 있는 레이블 모드) |
--field-input-padding-top | 1.5rem | 떠 있는 레이블이 차지하는 input 위쪽 공간 (떠 있는 레이블 모드) |
--field-label-weight | inherit | 레이블 굵기. 외부 레이블 모드는 medium |
--field-select-arrow | (SVG) | select 의 화살표 이미지 |
--field-select-arrow-size | 1rem | 화살표 크기 |
--field-select-padding-right | 2rem | 화살표 자리 오른쪽 여백 |
--field-min-height | 3.5rem | 최소 높이 |
--field-width | 100% | 너비 |
--field-input-padding-top | 1.5rem | 입력 상단 여백 |
--field-indicator-height | 0.0625rem | 하단 인디케이터 높이 |
--field-indicator-color | var(--color-text-muted) | 인디케이터 색상 |
--field-indicator-height-focus | 0.1875rem | 포커스 시 인디케이터 높이 |
--field-indicator-color-focus | var(--color-primary) | 포커스 시 인디케이터 색상 |
--field-outline-width | 0.0625rem | Outlined 테두리 두께 |
--field-outline-color | var(--color-border-strong) | Outlined 테두리 색상 |
--field-outline-width-focus | 0.1875rem | Outlined 포커스 시 두께 |
--field-outline-color-focus | var(--color-primary) | Outlined 포커스 시 색상 |
--field-font-size | 1rem | 입력 텍스트 크기 |
--field-color | var(--color-text) | 입력 텍스트 색상 |
--field-placeholder-color | var(--color-text-muted) | 플레이스홀더 색상 |
--field-caret-color | var(--color-primary) | 캐럿 색상 |
--field-label-size | 1rem | 라벨 크기 |
--field-label-size-float | 0.75rem | 플로팅 라벨 크기 |
--field-label-color | var(--color-text-muted) | 라벨 색상 |
--field-label-color-focus | var(--color-primary) | 포커스 시 라벨 색상 |
--field-supporting-size | 0.75rem | 보조 텍스트 크기 |
--field-supporting-color | var(--color-text-muted) | 보조 텍스트 색상 |
--field-icon-left | 0.75rem | 아이콘 왼쪽 위치 |
m3-checkbox (체크박스)
기본 사용법
소스 코드 보기
상태 변형
소스 코드 보기
색상 변형
소스 코드 보기
Variable API
| 변수 | 기본값 | 설명 |
|---|---|---|
--checkbox-size | 1.125rem | 체크박스 크기 (18dp) |
--checkbox-border-radius | 0.125rem | 모서리 둥글기 (2dp) |
--checkbox-border-width | 0.125rem | 테두리 두께 |
--checkbox-border-color | var(--color-text-muted) | 테두리 색상 |
--checkbox-background | transparent | 배경 |
--checkbox-check-color | var(--color-on-primary) | 체크 마크 색상 |
--checkbox-check-background | var(--color-primary) | 선택 시 배경 |
--checkbox-gap | 0.75rem | 라벨과의 간격 |
--checkbox-label-size | 0.875rem | 라벨 크기 |
--checkbox-label-color | var(--color-text) | 라벨 색상 |
--checkbox-state-size | 2.5rem | State layer 크기 |
--checkbox-state-color | var(--color-primary) | State layer 색상 |
m3-radio (라디오 버튼)
기본 사용법
소스 코드 보기
비활성화
소스 코드 보기
색상 변형
소스 코드 보기
Variable API
| 변수 | 기본값 | 설명 |
|---|---|---|
--radio-size | 1.25rem | 라디오 크기 (20dp) |
--radio-touch-size | 2.5rem | 터치 영역 |
--radio-stroke-width | 0.125rem | 테두리 두께 |
--radio-border-color | var(--color-text-muted) | 테두리 색상 |
--radio-background | transparent | 배경 |
--radio-dot-size | 0.625rem | 내부 점 크기 (10dp) |
--radio-dot-color | var(--color-primary) | 내부 점 색상 |
--radio-selected-color | var(--color-primary) | 선택 시 테두리 색상 |
--radio-gap | 0.75rem | 라벨과의 간격 |
--radio-label-size | 0.875rem | 라벨 크기 |
--radio-label-color | var(--color-text) | 라벨 색상 |
--radio-state-hover-opacity | 0.08 | 호버 투명도 |
--radio-state-pressed-opacity | 0.12 | 눌림 투명도 |
m3-switch (스위치)
토글 스위치입니다. 트랙 52x32dp, 핸들 16dp(off)/24dp(on)/28dp(pressed) 크기를 따릅니다.
기본 사용법
소스 코드 보기
비활성화
소스 코드 보기
색상 변형
소스 코드 보기
Variable API
| 변수 | 기본값 | 설명 |
|---|---|---|
--switch-gap | 0.75rem | 라벨과의 간격 |
--switch-track-width | 3.25rem | 트랙 너비 (52dp) |
--switch-track-height | 2rem | 트랙 높이 (32dp) |
--switch-track-radius | var(--radius-full) | 트랙 모서리 |
--switch-track-color | var(--color-surface-2) | 트랙 색상 (꺼짐) |
--switch-track-border | 0.125rem solid var(--color-border-strong) | 트랙 테두리 (꺼짐) |
--switch-track-color-checked | var(--color-primary) | 트랙 색상 (켜짐) |
--switch-track-border-checked | 0.125rem solid var(--color-primary) | 트랙 테두리 (켜짐) |
--switch-handle-size | 1rem | 핸들 크기 (꺼짐, 16dp) |
--switch-handle-size-checked | 1.5rem | 핸들 크기 (켜짐, 24dp) |
--switch-handle-size-pressed | 1.75rem | 핸들 크기 (눌림, 28dp) |
--switch-handle-radius | var(--radius-full) | 핸들 모서리 |
--switch-handle-color | var(--color-border-strong) | 핸들 색상 (꺼짐) |
--switch-handle-color-checked | var(--color-on-primary) | 핸들 색상 (켜짐) |
--switch-handle-offset | 0.375rem | 핸들 오프셋 |
--switch-label-size | 0.875rem | 라벨 크기 |
--switch-label-color | var(--color-text) | 라벨 색상 |
m3-slider (슬라이더)
연속(continuous) 및 이산(discrete) 슬라이더를 지원합니다.
기본 사용법 (Continuous)
소스 코드 보기
Discrete (눈금)
소스 코드 보기
색상 변형
소스 코드 보기
Variable API
| 변수 | 기본값 | 설명 |
|---|---|---|
--slider-width | 100% | 슬라이더 너비 |
--slider-padding | 0.5rem 0 | 여백 |
--slider-track-height | 0.25rem | 트랙 높이 (4dp) |
--slider-track-color | var(--color-primary-subtle) | 비활성 트랙 색상 |
--slider-track-active-color | var(--color-primary) | 활성 트랙 색상 |
--slider-track-border-radius | var(--radius-full) | 트랙 모서리 |
--slider-handle-size | 1.25rem | 핸들 크기 (20dp) |
--slider-handle-color | var(--color-primary) | 핸들 색상 |
--slider-handle-border-radius | var(--radius-full) | 핸들 모서리 |
--slider-handle-shadow | var(--shadow-sm) | 핸들 그림자 |
--slider-handle-border | none | 핸들 테두리 |
m3-stepper (수량 스테퍼, newtil 확장)
장바구니·상품 상세의 수량 −/＋ 입력. 한 테두리 안에 빼기 · 숫자 · 더하기가 붙어 있고, 브라우저의 숫자 스핀 버튼은 숨깁니다(남기면 자리를 차지해 숫자가 왼쪽으로 쏠립니다). 값을 바꾸는 동작은 앱이 맡습니다.
소스 코드 보기
| 클래스 | 설명 |
|---|---|
stepper:outlined (기본) / stepper:separated | 한 테두리 안에 붙음 / 버튼과 입력이 각각 둥근 상자 |
stepper-size:sm / md (기본) / lg | 높이 28 / 34 / 40px |
Variable API
| 변수 | 기본값 | 설명 |
|---|---|---|
--stepper-height | 2.125rem | 전체 높이 |
--stepper-btn-width | 2rem | −/＋ 버튼 폭 |
--stepper-input-width | 2.75rem | 숫자 입력 폭 |
--stepper-border-color | var(--color-border) | 테두리·구분선 색 |
--stepper-border-radius | var(--radius-2) | 모서리 |
--stepper-font-size / --stepper-font-weight | body-sm / semibold | 숫자 글꼴 |
select · 도움말 · 레이블 요소
select
select 도 input·textarea 와 같은 상자를 씁니다. 브라우저 기본 화살표는 지우고 --field-select-arrow 로 그립니다. 떠 있는 레이블은 :placeholder-shown 에 기대므로 select 는 외부 레이블 모드(field-label:top 등) 또는 field-label:none 과 함께 씁니다.
소스 코드 보기
도움말 위치
field-supporting 은 레이블·입력 뒤에 옵니다(order: 2). 외부 레이블 모드에서도 입력 상자 아래에 놓입니다.
레이블 요소
레이블은 label 요소가 기본이지만, label 이 아닌 요소(span 등)를 쓸 때는 field-label 클래스를 붙이면 같은 취급을 받습니다. 외부 레이블 모드는 레이블을 떠 있는 힌트가 아니라 본문 레이블로 보고 글자색 --color-text, 크기 0.8125rem, 굵기 medium 을 기본으로 합니다.
m3-form (폼 레이아웃, newtil 확장)
M3 스펙에는 Form 컴포넌트가 없습니다. m3-form 은 폼의 공통 배치(헤더 / 메시지 / 필드 / 액션)를 표준화하기 위한 newtil 확장입니다.
기본 사용법
소스 코드 보기
선택지 묶음 (form-group)
라디오·체크박스·칩 여러 개를 레이블 하나 아래에 묶습니다. form-group:inline 은 레이블 칸 옆에 선택지가 한 줄로 옵니다(좁은 화면에선 위아래). 선택지 옆 부가 설명은 form-choice-extra.
소스 코드 보기
| 클래스 | 설명 |
|---|---|
form-group | 레이블(form-group-label) + 선택지 줄(form-group-choices) 세로 묶음 |
form-group:inline | 레이블 칸(--form-group-label-width 5.5rem) 옆에 선택지 한 줄 |
form-choice-extra | 선택지 옆 부가 설명(작고 옅게) |
옵션 클래스
| 클래스 | 설명 |
|---|---|
form-header | 헤더 영역 |
form-headline | 제목 |
form-description | 설명 문구 |
form-fields | 입력 필드 묶음 |
form-actions | 버튼 영역 |
form-actions:start / form-actions:center / form-actions:end | 버튼 정렬 |
form-actions:between | 버튼 양끝 배치 |
form-actions:stretch | 버튼을 가로로 늘림 |
form-message | 안내 메시지 |
form-message:info / form-message:success / form-message:warning / form-message:error | 메시지 종류 |
시각 속성은 --form-* 변수로 노출됩니다. 변수 목록은 css/component/m3/m3-form.css 의 변수 선언 블록을 참고하세요.