본문으로 건너뛰기

CheckBox

이 컨트롤은 무엇인가요?​

CheckBox는 브라우저 네이티브 <input type="checkbox"> 엘리먼트를 그대로 사용하면서, 여기에 syn-datafield, syn-options, syn-events 속성을 붙여 체크 여부에 따라 원하는 값(문자열, 코드값 등)을 폼 데이터로 주고받을 수 있게 "강화(enhancement)"해주는 컨트롤입니다. 다른 컨트롤들(DropDownList, TreeView 등)처럼 커스텀 태그(<syn_xxx>)를 쓰는 것이 아니라, 이미 있는 <input type="checkbox"> 태그에 속성만 추가하면 되므로 가장 가볍고 배우기 쉬운 컨트롤입니다.

체크박스 자체의 boolean 상태(체크됨/안됨)는 그대로 두되, 실제로 서버에 저장하거나 화면 로직에서 쓰는 값은 checkedValue(기본 '1') / uncheckedValue(기본 '0')로 자유롭게 매핑할 수 있는 것이 핵심 기능입니다. 예를 들어 체크되면 'Y', 안되면 'N'을 넘기고 싶다면 옵션만 바꾸면 되고, HTML이나 페이지 스크립트를 따로 고칠 필요가 없습니다.

언제 사용하나요?​

  • 사용 여부(UseYN), 동의 여부(AgreeYN) 처럼 On/Off 두 가지 상태를 표현할 때
  • 목록 화면에서 여러 항목을 각각 체크해서 일괄 처리(선택 삭제, 선택 다운로드 등)할 때
  • 폼에서 "이용약관에 동의합니다"와 같이 단일 항목의 동의/거부를 받을 때
  • 여러 개의 체크박스를 같은 name으로 묶어 그룹을 이루고, getGroupNames()로 화면에 존재하는 체크박스 그룹 이름들을 한 번에 조회하고 싶을 때

CheckBox는 "여러 개 중 하나만" 고를 때 쓰는 RadioButton과 다릅니다. RadioButton은 같은 그룹 내에서 상호 배타적으로 하나만 선택되지만, CheckBox는 각 항목이 독립적으로 켜지고 꺼집니다. 또한 선택지가 많거나 목록 데이터를 기반으로 다중 선택 UI를 구성해야 한다면(콤보박스 형태의 드롭다운에 체크박스 목록을 넣는 경우) DropDownCheckList처럼 리스트 데이터 바인딩을 지원하는 컨트롤을 쓰는 것이 더 적합합니다. 화면에 이미 고정된 개수의 체크박스를 하나하나 배치하는 경우라면 CheckBox로 충분합니다.

빠른 시작​

가장 단순한 형태는 syn-datafield만 지정하면 됩니다.

<input id="chkAgree" type="checkbox" syn-datafield="AgreeYN">
<label for="chkAgree">이용약관에 동의합니다</label>

체크/미체크 값을 직접 지정하고 라벨을 자동으로 붙이고 싶다면 syn-options에 toSynControl: true와 textContent를 함께 지정합니다(toSynControl이 false인 기본값 상태에서는 textContent/disabled 옵션이 적용되지 않습니다 — 자세한 내용은 아래 "Options (defaultSetting)"의 toSynControl 설명 참고).

<input id="chkUseYN" type="checkbox" syn-datafield="UseYN"
    syn-options="{toSynControl: true, checkedValue: 'Y', uncheckedValue: 'N', textContent: '사용 여부'}">

값 변경을 감지하려면 syn-events에 change를 등록하고, 페이지 스크립트(<페이지파일명>.js)에 <엘리먼트ID>_change 함수를 정의합니다.

<input id="chkNotify" type="checkbox" syn-datafield="NotifyYN" syn-events="['change']">
'use strict';
let $mypage = {
    event: {
        chkNotify_change(evt) {
            var value = syn.uicontrols.$checkbox.getValue('chkNotify');
            syn.$l.eventLog('chkNotify_change', 'value: ' + value);
        }
    }
}

페이지에는 위 스크립트 외에 다음 한 줄만 있으면 됩니다. syn.loader.js가 화면에 있는 컨트롤들을 스캔해서 필요한 CSS/JS를 알아서 불러옵니다.

<script src="/js/syn.loader.js"></script>

예제 실행하기​

example/ 폴더에 3가지 예제가 있습니다. 로컬 서버 실행 후 브라우저에서 아래 경로로 접근해서 확인하세요 (예: /uicontrols/CheckBox/example/basic.html).

  • basic.html / basic.js — 옵션 없이 가장 단순하게 사용하는 기본 체크박스와, checked 속성으로 기본 체크 상태를 지정하는 예제입니다.
  • options.html / options.js — checkedValue / uncheckedValue로 커스텀 값(Y/N, ACTIVE/INACTIVE 등)을 지정하는 방법, disabled로 비활성화하는 방법, 같은 name으로 여러 체크박스를 묶어 배치하고 getGroupNames()로 그룹명을 조회하는 방법을 보여줍니다.
  • events.html / events.js — syn-events="['change']"로 변경 이벤트를 감지하고, 버튼을 눌러 getValue / setValue / toggleValue / clear 메서드를 직접 호출해보는 예제입니다.
  • toggledependent.html / toggledependent.js — 실무 패턴: 체크 여부에 따라 옆의 DatePicker에 오늘 날짜를 자동으로 채우거나 비우고, getValue가 반환하는 값이 boolean이 아니라 checkedValue/uncheckedValue 문자열임을 보여줌

더 알아보기​

옵션, 메서드, 이벤트의 전체 목록과 시그니처는 아래 API 참조 섹션를 참고하세요.

실전 예제 페이지​

/uicontrols/CheckBox/example/ 경로의 예제를 아래 iframe에서 바로 확인할 수 있습니다.

basic.html​

events.html​

options.html​

toggledependent.html​

features.html​

practical.html​

소스와 로드 파일​

항목내용
컨트롤CheckBox
전역 별칭syn.uicontrols.$checkbox
버전v2025.10.1
소스uicontrols/CheckBox/CheckBox.js
스타일uicontrols/CheckBox/CheckBox.css

API 참조​

syn.uicontrols.$checkbox (버전: v2025.10.1)

소스: uicontrols/CheckBox/CheckBox.js, uicontrols/CheckBox/CheckBox.css

마크업​

CheckBox는 커스텀 태그가 아니라 네이티브 <input type="checkbox">를 강화(enhancement)하는 방식입니다.

<input id="elId" type="checkbox" syn-datafield="Field"
    syn-options="{checkedValue: 'Y', uncheckedValue: 'N', textContent: '사용 여부'}"
    syn-events="['change']">
  • id : 컨트롤 식별자(필수). 메서드 호출 시 elID로 사용합니다.
  • syn-datafield : 폼 전송/바인딩 시 사용할 필드명.
  • syn-options : defaultSetting을 덮어쓸 JSON(객체 리터럴) 문자열. 생략하면 기본값이 적용됩니다.
  • syn-events : 페이지 스크립트의 <elID>_<eventName> 핸들러와 연결할 이벤트명 배열.
  • checked : 초기 체크 상태는 네이티브 checked 속성으로 지정합니다(HTML 표준 방식 그대로).
  • disabled : 네이티브 disabled 속성 또는 syn-options의 disabled 값으로 지정할 수 있습니다.

Options (defaultSetting)​

옵션명타입기본값설명
contentsstring''다른 컨트롤과 공통으로 쓰이는 예약 필드입니다. CheckBox 내부 로직에서는 실제로 참조되지 않습니다.
toSynControlbooleanfalsetrue로 설정하면 원본 <input>을 숨기고(_hidden 접미사 부여) span.form-control 래퍼 안에 새 <input class="ui_checkbox">와 <label>을 자동 생성해 렌더링합니다. false면 원본 <input>에 syn-options만 부여하고 그대로 사용합니다.
disabledbooleanfalse체크박스 비활성화 여부. toSynControl: true일 때는 새로 생성되는 <input>의 disabled 속성에 반영됩니다.
checkedValuestring'1'체크되었을 때 getValue가 반환할 값이자, setValue 호출 시 이 값과 일치하면 체크 상태로 처리하는 기준값입니다.
uncheckedValuestring'0'체크 해제되었을 때 getValue가 반환할 값입니다.
dataTypestring'string'값의 데이터 타입 힌트(다른 컨트롤과 공통 스키마).
belongIDstring | nullnull상위 컨테이너/그룹 식별자(공통 스키마).
controlTextany | nullnull공통 스키마에 포함된 예약 필드로, CheckBox 내부 로직에서는 실제로 사용되지 않습니다.
textContentstring''toSynControl: true일 때 체크박스 옆에 표시할 <label> 텍스트입니다.
validatorsobject | nullnull유효성 검증 설정(공통 스키마).
transactConfigobject | nullnull트랜잭션(서버 호출) 연동 설정(공통 스키마). triggerEvent를 지정하면 해당 이벤트 발생 시 자동으로 트랜잭션이 실행됩니다.
triggerConfigobject | nullnull트리거 연동 설정(공통 스키마).

메서드​

메서드시그니처설명
controlLoadcontrolLoad(elID, setting)컨트롤 초기화(생성자 역할). syn.loader.js가 화면 스캔 시 자동으로 호출하며, 개발자가 직접 호출할 일은 없습니다.
getValuegetValue(elID, meta)체크 상태에 따라 checkedValue 또는 uncheckedValue를 반환합니다. syn-options가 없으면 checked 여부에 따라 '1'/'0'을 반환합니다.
setValuesetValue(elID, value, meta)value가 falsy(빈 문자열, null, false 등)면 무조건 체크 해제합니다. truthy면 value.toString().toUpperCase()가 checkedValue와 정확히 일치할 때만 체크 상태로 설정합니다. ⚠ checkedValue는 controlLoad 이후 항상 정의되어 있으므로(기본값 '1'), setValue(elID, true)처럼 JS 불리언 true를 넘기면 'TRUE'로 변환되어 checkedValue(예: '1')와 일치하지 않아 오히려 체크가 해제됩니다. 체크시키려면 setValue(elID, checkedValue와 같은 문자열)(예: checkedValue가 '1'이면 setValue(elID, '1'))을 넘기세요.
toggleValuetoggleValue(elID)현재 체크 상태를 반전시킵니다(체크→해제, 해제→체크).
clearclear(elID, isControlLoad)체크 상태를 false(미체크)로 초기화합니다.
getGroupNamesgetGroupNames()현재 화면(document) 안의 모든 input[type='checkbox']가 가진 name 속성 값을 중복 제거해서 배열로 반환합니다.
setLocalesetLocale(elID, translations, control, options)다국어 처리 훅입니다. CheckBox는 현재 별도 구현 없이 빈 함수로 제공됩니다.
addModuleListaddModuleList(el, moduleList, setting, controlType)폼 제출 시 참조할 모듈 목록에 컨트롤 정보를 등록하는 내부용 메서드입니다. 직접 호출하지 않습니다.

이벤트 (syn-events)​

CheckBox는 별도의 eventHooks 배열을 선언하지 않는 컨트롤입니다. 네이티브 <input type="checkbox">를 그대로 사용하기 때문에, syn-events 속성에 등록한 이벤트명은 syn.$l.addEvent(elID, eventName, handler)를 통해 표준 DOM 이벤트로 그대로 연결됩니다. 즉 브라우저가 지원하는 어떤 이벤트명이든 등록할 수 있지만, 실무에서는 아래 이벤트가 주로 사용됩니다.

이벤트명핸들러 시그니처설명발생 시점
change<elID>_change(evt)체크 상태가 사용자 조작(클릭, 키보드 스페이스 등)으로 바뀌었을 때 발생하는 표준 DOM change 이벤트입니다.체크박스의 체크 여부가 바뀌고 포커스가 유지된 상태에서 값이 확정될 때
click<elID>_click(evt)체크박스를 클릭했을 때 발생하는 표준 DOM click 이벤트입니다.체크박스 영역(또는 연결된 <label>) 클릭 시

핸들러는 evt 인자(네이티브 Event 객체) 하나만 전달받습니다. 현재 값을 확인하려면 핸들러 안에서 syn.uicontrols.$checkbox.getValue(elID)를 호출하면 됩니다.

참고​

  • 실행 가능한 예제: example/basic.html, example/options.html, example/events.html
  • 초보자용 개요와 사용 시나리오: 이 문서의 사용법 섹션
  • 스타일 커스터마이징: CheckBox.css의 .syn-checkbox 클래스를 통해 색상 등을 재정의할 수 있습니다.