Skip to Content
ComponentsCalsHidden

Hidden

화면에 표시되지 않으면서 키-값 데이터를 보유하는 숨김 입력 컴포넌트

개요

Cals Hidden은 화면에 보이지 않는 <input type="hidden">을 렌더하여, 폼/서버 전송 페이로드에 포함될 키-값 데이터를 선언적으로 보유하는 컴포넌트입니다. 사용자에게 노출되지 않는 식별자·상태값 등을 폼과 함께 전송할 때 사용합니다.

주요 특징

  • ✅ 시각 출력 없음: type=“hidden”으로 렌더되어 레이아웃에 영향을 주지 않음
  • ✅ controlled / uncontrolled: value(변경 시 즉시 반영) 또는 defaultValue로 값 관리
  • ✅ 페이로드 키: name prop으로 전송 키 지정
  • ✅ 표준 속성 전달: id, data-* 등 표준 input 속성 그대로 전달
  • ✅ 요소 참조: ref로 내부 input 요소(값) 접근

기본 사용

name(페이로드 키)과 value를 지정합니다. 화면에는 아무 것도 렌더되지 않습니다.

(화면 출력 없음 — name=token, value=hidden-value)

기본값 (Uncontrolled)

defaultValue로 초기 보유 값을 지정합니다.

(화면 출력 없음 — defaultValue=init-value)

표준 속성 전달

id, data-* 등 표준 input 속성을 그대로 전달합니다. 프로젝트팀 공통 파이프라인이 암호화/번역 등 메타 정보를 부여할 때 활용합니다.

(화면 출력 없음 — data-encrypt 부여)

API Reference

Props

React.InputHTMLAttributes<HTMLInputElement>를 확장하므로 name, id, data-* 등 표준 input 속성을 모두 지원합니다.

PropTypeDefaultDescription
valuestring | number-보유 값 (controlled, 변경 시 즉시 반영)
defaultValuestring | number-초기 보유 값 (uncontrolled)
namestring-페이로드 전송 키 (input name 속성)
idstring-input id 속성
...restInputHTMLAttributes-data-* 등 표준 input 속성 그대로 전달
refRef<HTMLInputElement>-내부 input 요소 참조

type은 항상 "hidden"으로 고정됩니다. type=“hidden” input은 사용자 입력으로 change 이벤트를 발생시키지 않으므로 onChange 콜백은 제공하지 않으며, 값은 value prop / ref로 다룹니다.

접근성

권장 사항

  • ✅ 사용자에게 노출하지 않을 식별자·상태값 보유에 사용
  • ✅ type=“hidden”은 포커스/탭 순서와 보조기술에서 제외됨
  • ❌ 사용자에게 보여야 하는 값에는 사용하지 말 것 (대신 Input/Label 사용)

관련 컴포넌트

  • Input: 사용자에게 보이는 텍스트 입력
  • Label: 데이터 표시 컴포넌트
Last updated on
ButtonInput