Number input

Number input (숫자 입력)

숫자 입력은 사용자가 숫자 값을 입력하고, 두 부분으로 된 컨트롤로 값을 점진적으로 늘리거나 줄일 수 있게 해주는 컴포넌트예요. 작은 값을 조정할 때 입력 노력을 줄여줍니다.

출처: Number input

본문

AI 라벨이 있는 숫자 입력 with AI label이 이제 안정(stable) 버전이 됐어요. 이 추가는 컴포넌트의 시각적 모양을 바꾸고, 컴포넌트에 AI가 있을 때 AI 설명 가능성 기능을 도입합니다. 자세한 내용은 AI 존재(AI presence) 섹션을 참고하세요.

개요 (Overview)

숫자 입력은 텍스트 입력과 비슷하지만 숫자 값만 지정하는 데 사용해요. 숫자 입력은 두 부분으로 된 컨트롤로 값을 점진적으로 늘리거나 줄입니다. 숫자 입력은 작은 값을 조정하기 위한 입력 노력을 줄여줍니다.

언제 사용할까요 (When to use)

사용자가 숫자 값을 입력해야 할 때.
작은 값을 조정할 때, 늘리거나 줄이는데 몇 번의 클릭만 필요할 때.
사용자가 정확한 값을 모르고 현재 상태에 상대적인 값만 바꾸고 싶을 때.

언제 사용하지 말아야 할까요 (When not to use)

큰 값 변경이 예상된다면 숫자 입력을 사용하지 않는 것이 모범 사례예요. 예를 들어 값이 1에서 30으로 설정될 때, 30에 도달하려면 많은 클릭이 필요하므로 숫자 입력은 좋은 선택이 아닙니다. 이 경우 숫자 값이 크거나 숫자 옵션의 범위가 넓을 때는 슬라이더(slider)를 사용하세요.
가격, 거리, 길이, 사람 키 같은 연속 변수에는 숫자 입력을 피하는 것도 좋아요. 넓은 범위 안에서 정확한 값이 중요할 때는 텍스트 입력(text input)을 대신 사용하세요.

포맷 (Formatting)

구조 (Anatomy)

Default
Fluid
라벨(Label): 사용자에게 필드에 입력해야 할 콘텐츠에 대해 알려주는 텍스트. 승인된 접근성 예외가 없으면 필수입니다.
숫자 값(Numeric value): 사용자가 필드에 값을 입력하거나 빼기·더하기 컨트롤을 사용하면 값이 바뀝니다.
헬퍼 텍스트(Helper text): 사용자에게 추가 도움 또는 컨텍스트를 제공할 수 있는 보조 텍스트. 올바른 데이터 형식을 설명하는 데 자주 사용됩니다.
필드(Field): 사용자가 데이터를 입력하는 컨테이너.
빼기 아이콘(Subtract icon): 감소 값을 트리거하는 아이콘.
더하기 아이콘(Add icon): 증가 값을 트리거하는 아이콘.
상태 아이콘(Status icon): number input의 상태(오류 또는 경고)를 나타냅니다.
오류 또는 경고 텍스트(Error or Warning text): 오류나 경고 상태가 나타나면 헬퍼 텍스트를 대체합니다.

스타일링 (Styling)

숫자 입력에는 기본(default)과 플루이드(fluid)의 두 가지 스타일이 있어요. 기능은 같지만 시각적으로 다르게 보이며, 어디에 사용할지에 영향을 줍니다.

스타일 (Style)	모양 (Appearance)	사용 사례 (Use case)
Default	라벨이 입력 필드 바깥과 위에 배치되는 전통적인 스타일.	입력 컴포넌트 사이에 여백이 필요하거나 공간이 빠듯하고 더 작은 컴포넌트가 필요한 생산적(productive) 순간에 사용.
Fluid	라벨이 입력 필드 안에 배치되고 사용자 입력 텍스트와 인라인으로 겹쳐지는 대체 스타일.	표현적(expressive) 순간, 플루이드 폼, 제한된 공간, 또는 툴바 같은 복잡한 컴포넌트에 붙일 때 사용.

왼쪽에 기본 스타일 입력, 오른쪽에 플루이드 스타일.

크기 (Sizing)

기본 입력 높이 (Default input heights)

숫자 입력에는 small, medium, large의 세 가지 기본 입력 높이 크기가 있어요. 너비는 콘텐츠, 레이아웃, 디자인에 따라 크기가 달라집니다.

크기 (Size)	높이 (px/rem)	사용 사례 (Use case)
Small (sm)	32 / 2	공간이 제한되거나 길고 복잡한 폼에 숫자 입력을 배치할 때 사용.
Medium (md)	40 / 2.5	기본 크기이며 가장 흔히 사용되는 크기. 확신이 없으면 중간 크기를 사용.
Large (lg)	48 / 3	작업할 공간이 많을 때 사용. 큰 크기는 보통 단순한 폼이나 숫자 입력이 페이지에 단독으로 배치될 때 사용.

플루이드 입력 높이 (Fluid input heights)

플루이드 입력 높이는 하나뿐이며 기본 높이보다 시각적으로 더 커요. 입력은 경고나 오류 메시지가 하단에 추가된 경우를 제외하고 64px의 설정된 높이를 가집니다.

콘텐츠 (Content)

주요 요소 (Main elements)

라벨 (Label)

사용자가 필드를 완성하는 방법을 알도록 항상 라벨을 포함하세요.
라벨을 짧고 간결하게 유지하세요.
라벨에 문장식 대소문자(sentence-style capitalization)를 사용하세요.

라벨을 포함하세요.

숫자 입력의 컨텍스트를 이해하는 데 도움이 되는 라벨을 숨기지 마세요.

헬퍼 텍스트 (Helper text)

입력 값에 최대값이나 최소값이 있다면 그것을 나타내요.
헬퍼 텍스트는 선택 사항이지만, 있으면 필요할 때 경고 및 오류 메시지로 대체됩니다.

넘침 콘텐츠 (Overflow content)

라벨, 숫자 값, 헬퍼 텍스트는 짧아야 하며 두 줄을 초과해서는 안 됩니다.

동작 (Behaviors)

상태 (States)

숫자 입력은 필드와 컨트롤 요소 모두에 일련의 상태가 있습니다: enabled, hover, focus, error, warning, disabled, read-only.

상태 (State)	언제 사용하나요 (When to use)
Enabled	숫자 입력이 활성화되어 있지만 사용자가 직접 상호작용하지 않을 때. 보통 컴포넌트의 기본 또는 정상 상태라고 함. 활성 숫자 입력 필드는 기본값을 포함해야 함.
Hover	사용자의 마우스 커서가 필드나 버튼 컨트롤 위에 있을 때.
Focus	사용자가 숫자 입력에 탭하거나 클릭하면 필드나 컨트롤이 포커스되어, 사용자가 컴포넌트로 성공적으로 이동했음을 나타냄.
Error	필수 숫자 입력이 채워지지 않았을 때. 시스템 오류로 인해 발생할 수도 있음. 데이터를 제출·저장하기 전에 사용자 응답이 필요함.
Warning	예외 조건에 사용자의 주의를 환기해야 할 때. 그 조건은 오류가 아닐 수 있지만 해결되지 않으면 문제를 일으킬 수 있음.
Disabled	사용자가 컴포넌트와 상호작용할 수 없고 모든 인터랙티브 기능이 제거되었을 때. 읽기 전용 상태와 달리 비활성 상태는 포커스할 수 없고, 화면 판독기로 읽히지 않으며, 시각 대비를 통과할 필요가 없어 해석이 필요하면 접근성이 떨어짐.
Skeleton	초기 페이지 로드 시 숫자 입력이 아직 완전히 로드되지 않았음을 나타내는 데 사용.
Read-only	사용자가 컴포넌트를 검토할 수 있지만 수정할 수 없을 때. 비활성 상태처럼 모든 인터랙티브 기능을 제거하지만 여전히 포커스 가능하고, 화면 판독기로 접근 가능하며, 가독성을 위해 시각 대비를 통과함.

Default
Fluid

인터랙션 (Interactions)

마우스 (Mouse)

사용자는 입력 필드를 클릭하고 입력 필드 안에 입력해 값을 바꿀 수 있어요. 사용자는 더하기 또는 빼기 아이콘 컨트롤을 눌러 값을 늘리거나 줄일 수도 있습니다.

Default
Fluid

키보드 (Keyboard)

사용자는 Tab을 눌러 숫자 입력 필드로 이동할 수 있어요. 그런 다음 Up arrow를 눌러 값을 늘리거나 Down arrow를 눌러 값을 줄일 수 있습니다.

검증 (Validation)

유효하지 않음 (Invalid)

데이터가 유효하지 않거나 필수 필드가 비어 있으면 오류 상태가 트리거됩니다. 오류 상태에는 잘못된 콘텐츠를 나타내는 세 가지 시각적 표시가 있어요: 빨간 테두리, 오류 아이콘 표시, 오류 메시지.

기본값 (Default values)

숫자 입력에는 항상 기본값이 있어야 해요. 기본값은 보통 '1'입니다. 때로는 입력 값이 '0'으로 기본 설정될 수 있어요. 예를 들어 호텔 방을 예약할 때 기본 성인 수를 '1'로, 기본 어린이 수를 '0'으로 설정할 수 있습니다.

대부분의 사용자가 선택할 가능성이 높은 명확한 기본값을 설정하세요.

값 입력을 비워 두지 마세요.

AI 존재 (AI presence)

숫자 입력에는 입력에 AI 라벨이 있을 때 AI 시각적 스타일링을 취하는 수정(modification)이 있어요. 숫자 입력의 AI 변형은 AI 라벨이 추가된 것 외에는 일반 버전과 동일하게 동작하며, AI 라벨은 시각적 표시이자 설명 가능성 팝오버의 트리거 역할을 합니다.

AI용 디자인에 대한 자세한 내용은 Carbon for AI 가이드라인을 참고하세요.

Default
Fluid

AI로 되돌리기 (Revert to AI)

숫자 입력은 사용자 인터랙션에 따라 AI 변형과 비-AI 변형 사이를 전환할 수 있어요. 사용자가 AI가 제안한 콘텐츠를 수동으로 재정의하면 입력은 AI 변형에서 비-AI 변형으로 바뀝니다. 편집 후에도 사용자는 revert to AI 버튼을 통해 처음에 AI로 생성된 콘텐츠로 다시 전환할 수 있어야 해요.

Default
Fluid

숫자 값이 크거나 숫자 옵션의 범위가 넓을 때는 슬라이더(slider)를 사용하세요.
넓은 범위 안에서 정확한 값을 지정하는 것이 중요할 때는 텍스트 입력(text input)을 대신 사용하세요.

참고 자료 (References)

Yuxuan (Tammy) Zhou, Design Guidelines for Input Steppers (Nielsen Norman Group, 2018)

더 알아보기 (Learn more)

숫자 입력은 작은 숫자 값을 조정하는 데 적합한 컴포넌트예요. 값 변경 범위가 크면 슬라이더를, 넓은 범위에서 정확한 연속 값이 필요하면 텍스트 입력을 쓰세요. 항상 명확한 기본값을 설정하고, 오류 상태에서는 빨간 테두리·상태 아이콘·오류 메시지로 사용자에게 정확히 알려야 합니다.