Checkbox

여러 항목을 독립적으로 선택하거나 동의 여부를 확인합니다.

<sy-checkbox>설치 안내 기본 사용법

Live preview

컴포넌트를 조작하면 여기에 결과가 표시됩니다.

코드 보기

HTML

<sy-checkbox
  checked
  name="notifications"
  value="email"
  id="sample"
>알림 이메일 받기</sy-checkbox>

사용 가이드

여러 항목을 독립적으로 켜고 끌 때 사용합니다. 서로 배타적인 한 가지 값은 Radio로 선택하게 하세요.

오류 문구는 error 슬롯에 작성합니다.
컴포넌트 안에 <span slot="error">오류 메시지</span>을 넣으세요. 글자뿐 아니라 링크 등 필요한 안내도 넣을 수 있습니다. noNativeValidity를 지원하는 입력은 이를 켜면 브라우저 팝업 대신 이 안내를 표시합니다. Switch는 항상 컴포넌트 아래에 오류를 표시합니다.
업무 규칙의 실패는 setCustomError()로 알립니다.
예를 들어 서버가 중복된 값을 거절하면 error 슬롯의 문구를 바꾸고 setCustomError()를 호출하세요. 이 메서드에는 메시지 인자를 전달하지 않습니다. 사용자 지정 오류가 있으면 폼 제출도 차단됩니다.
해결 후 해제하고 제출 가능 여부를 확인합니다.
clearCustomError()로 업무 규칙 오류를 해제하세요. required나 입력 형식 검사까지 해제되지는 않습니다. await checkValidity()는 true/false를, reportValidity()는 검사 결과와 오류 표시를 함께 제공합니다. name을 지정한 유효한 값은 제출 시 FormData로 읽습니다.

선택·해제

checked로 선택 상태를 관리합니다. 항목 하나를 바꿔도 다른 항목의 선택은 유지합니다.

일부 선택

indeterminate는 하위 항목의 일부만 선택되었음을 나타냅니다. 실제 checked 값은 앱에서 관리하세요.

예제

독립적인 복수 선택

각 항목을 따로 켜고 끌 수 있습니다.

AI 요청하기

다음 요소를 세로로 쌓아 줘. - sy-checkbox "디자인" — name: "teams", value: "0", checked: true - sy-checkbox "개발" — name: "teams", value: "1" - sy-checkbox "마케팅" — name: "teams", value: "2"

코드 보기

HTML

<div style="display:grid;gap:16px;width:100%">
  <sy-checkbox
    name="teams"
    value="0"
    checked
  >디자인</sy-checkbox>
  <sy-checkbox name="teams" value="1">개발</sy-checkbox>
  <sy-checkbox name="teams" value="2">마케팅</sy-checkbox>
</div>

일부 선택 상태

일부 항목이 선택됐음을 표현합니다. 누르면 사용자가 명확한 선택 상태로 바꿀 수 있습니다.

AI 요청하기

다음 컴포넌트를 만들어 줘. - sy-checkbox "전체 선택" — indeterminate: true

코드 보기

HTML

<sy-checkbox indeterminate>전체 선택</sy-checkbox>

비활성화와 읽기 전용

위에서부터 기본 상태, 비활성화, 읽기 전용입니다. 비활성화 항목은 포커스와 입력이 차단됩니다. 읽기 전용은 값을 유지하면서 수정을 막습니다.

AI 요청하기

다음 요소를 세로로 쌓아 줘. - sy-checkbox "이메일 알림" — checked: true - sy-checkbox "이메일 알림" — checked: true, disabled: true - sy-checkbox "이메일 알림" — checked: true, readonly: true

코드 보기

HTML

<div style="display:grid;gap:16px;width:100%">
  <sy-checkbox checked>이메일 알림</sy-checkbox>
  <sy-checkbox checked disabled>이메일 알림</sy-checkbox>
  <sy-checkbox checked readonly>이메일 알림</sy-checkbox>
</div>

이벤트와 전달 값

컴포넌트를 조작하고 최근 이벤트의 이름과 detail 값을 확인하세요. 코드에는 이 컴포넌트와 하위 구성 요소가 보내는 이벤트의 구독 방법이 모두 포함되어 있습니다.

AI 요청하기

다음 컴포넌트를 만들어 줘. - sy-checkbox "알림 이메일 받기" — checked: true, name: "notifications", value: "email" 최근 이벤트 표시: changed, focused, blured

코드 보기

HTML

<sy-checkbox
  checked
  name="notifications"
  value="email"
  id="sample"
>알림 이메일 받기</sy-checkbox>
<output id="demo-events" aria-live="polite">컴포넌트를 조작하면 최근 이벤트와 전달 값이 표시됩니다.
</output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  for (const name of ["changed", "focused", "blured"]) {
    document.addEventListener(name, event => {
      document.querySelector('#demo-events').textContent =
        `${event.target.localName} · ${name}: ${describeResult(event.detail)}`;
    });
  }
</script>

체크박스 보조 설명

checkboxTitle은 내부 체크박스의 title에 전달됩니다. 기본 슬롯에는 화면에 보일 문구를, title에는 추가 설명을 지정하세요.

AI 요청하기

다음 컴포넌트를 만들어 줘. - sy-checkbox "알림 이메일 받기" — checked: true, title: "프로젝트의 변경 사항을 이메일로 받습니다.", name: "notifications", value: "email" - JS 속성 checkboxTitle: "프로젝트의 변경 사항을 이메일로 받습니다."

코드 보기

HTML

<sy-checkbox
  checked
  title="프로젝트의 변경 사항을 이메일로 받습니다."
  name="notifications"
  value="email"
  id="sample"
>알림 이메일 받기</sy-checkbox>

<script type="module">
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "checkboxTitle": "프로젝트의 변경 사항을 이메일로 받습니다."
  });
</script>

폼과 유효성 검사

값을 비운 채 제출하면 필수 입력 검사가 동작합니다. 값을 입력한 뒤 제출해 폼 데이터를 확인하고, 사용자 지정 오류도 켜고 꺼보세요.

AI 요청하기

다음 컴포넌트를 만들어 줘. 폼 안에 넣어 줘. - sy-checkbox "약관에 동의합니다." — name: "field", required: true, value: "accepted" - span "동의가 필요합니다." (error 슬롯) 각 요소의 따옴표 안 문구를 그대로 유지해 줘. 슬롯 자식이 있어도 부모 요소의 문구를 생략하지 마.

코드 보기

HTML

<form style="display:grid;gap:16px">
  <sy-checkbox
    name="field"
    required
    value="accepted"
    id="sample"
  >약관에 동의합니다.<span slot="error">동의가 필요합니다.</span></sy-checkbox>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">제출</sy-button>
    <sy-button type="reset">초기화</sy-button>
  </div>
</form>
<div class="demo-actions"
  style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px"
>
  <sy-button id="action-0" size="small">유효성 확인</sy-button>
  <sy-button id="action-1" size="small">오류 표시</sy-button>
  <sy-button id="action-2" size="small">오류 해제</sy-button>
</div>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  const actionTarget0 = document.querySelector("#sample");
  document.querySelector('#action-0').addEventListener('click', async () => {
    const result = await actionTarget0.checkValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget1 = document.querySelector("#sample");
  document.querySelector('#action-1').addEventListener('click', async () => {
    const result = await actionTarget1.setCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget2 = document.querySelector("#sample");
  document.querySelector('#action-2').addEventListener('click', async () => {
    const result = await actionTarget2.clearCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

검사 결과와 오류 상태 읽기

제출 전에 검사하거나 오류를 화면에 표시할 수 있습니다. 필수 값을 비워 두고 검사한 다음, 값을 채워 반환 값이 어떻게 달라지는지 확인하세요. 상태 조회는 사용자 지정 오류와 필수 입력 오류를 구분하는 데 사용합니다.

AI 요청하기

코드 보기

HTML

<form style="display:grid;gap:16px">
  <sy-checkbox
    name="field"
    required
    value="accepted"
    id="sample"
  >약관에 동의합니다.<span slot="error">동의가 필요합니다.</span></sy-checkbox>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">제출</sy-button>
    <sy-button type="reset">초기화</sy-button>
  </div>
</form>
<div class="demo-actions"
  style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px"
>
  <sy-button id="action-0" size="small">유효성 확인</sy-button>
  <sy-button id="action-1" size="small">오류 표시</sy-button>
  <sy-button id="action-2" size="small">오류 해제</sy-button>
  <sy-button id="action-3" size="small">오류와 함께 검사</sy-button>
  <sy-button id="action-4" size="small">검증 상태 조회</sy-button>
</div>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  const actionTarget0 = document.querySelector("#sample");
  document.querySelector('#action-0').addEventListener('click', async () => {
    const result = await actionTarget0.checkValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget1 = document.querySelector("#sample");
  document.querySelector('#action-1').addEventListener('click', async () => {
    const result = await actionTarget1.setCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget2 = document.querySelector("#sample");
  document.querySelector('#action-2').addEventListener('click', async () => {
    const result = await actionTarget2.clearCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget3 = document.querySelector("#sample");
  document.querySelector('#action-3').addEventListener('click', async () => {
    const result = await actionTarget3.reportValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget4 = document.querySelector("#sample");
  document.querySelector('#action-4').addEventListener('click', async () => {
    const result = await actionTarget4.getValidStatus();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

사용자 지정 오류 메시지

서버 중복 검사나 업무 규칙에 맞지 않을 때 오류 문구를 직접 표시합니다. 아래 문구를 바꿔 보고 제출을 눌러 차단되는지 확인하세요. 오류 해제 후에는 필수 입력 조건까지 만족해야 제출됩니다.

코드 보기

HTML

<label for="error-message">표시할 오류 메시지</label><input
  id="error-message"
  value="서버에서 이 값을 승인하지 않았습니다. 내용을 확인해 주세요."
  type="text"
>
<form style="display:grid;gap:16px">
  <sy-checkbox
    no-native-validity
    name="field"
    required
    value="accepted"
    id="sample"
  >약관에 동의합니다.<span slot="error">동의가 필요합니다.</span></sy-checkbox>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">제출</sy-button>
    <sy-button type="reset">초기화</sy-button>
  </div>
</form>
<div class="demo-actions">
  <sy-button id="show-custom-error" variant="primary">오류 표시</sy-button>
  <sy-button id="clear-custom-error">오류 해제</sy-button>
</div>
<output id="custom-error-result" aria-live="polite"></output>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  await (async function customErrorSetup(root) {
    const field = root.querySelector('#sample');
    const message = root.querySelector('[slot="error"]');
    const input = root.querySelector('#error-message');
    const output = root.querySelector('#custom-error-result');
    const update = async () => {
      message.textContent = input.value.trim() || _msg("m_4eea8cef81c6");
      await field.setCustomError();
      output.textContent = _msg("m_e00bd46236d3", [message.textContent]);
    };
    input.addEventListener('input', update);
    root.querySelector('#show-custom-error').addEventListener('click', update);
    root.querySelector('#clear-custom-error').addEventListener('click', async () => {
      await field.clearCustomError();
      output.textContent = await field.checkValidity() ? _msg("m_c454251167b2") : _msg(
        "m_5b8cb48627e5");
    });
    root.querySelector('form').addEventListener('invalid', () => {
      output.textContent = _msg("m_c702c7778166");
    }, true);
    root.querySelector('form').addEventListener('reset', () => {
      output.textContent = _msg("m_b90c2b4dc30f");
    });
    await update();
  })(document);
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

기능별 예제

10개 주제에서 필요한 기능을 선택하세요. 속성 설정, 메서드 호출, 이벤트 결과와 슬롯 구성을 실행 화면과 코드로 확인할 수 있습니다.

기능 찾기

사용 예제 · Overview

선택한 예제를 직접 조작해 보세요. 여러 구성이 있는 주제는 세부 예제를 바꿀 수 있습니다.

코드 보기

HTML

예제를 불러오고 있습니다.