KRDS Angular

폼 그룹 Form group ​

<krds-form-group>은 입력 요소 하나와 그 레이블·도움말을 묶는 .form-group 영역입니다. 안에 넣은 입력 요소(krdsInput·krdsSelect·krdsControl)에 레이블과 도움말을 자동으로 연결합니다. 텍스트 입력 필드, 텍스트 영역, 셀렉트, 날짜 입력 필드 등과 함께 씁니다.

기본 ​

label은 입력 필드 위의 레이블(.form-tit 안의 <label>), hint는 입력 필드 아래의 도움말(<p>)이 됩니다. 레이블의 for는 안에 넣은 입력 요소의 id로, 도움말은 입력 요소의 aria-describedby로 연결됩니다. 입력 요소의 id는 자동으로 만들어지고, 직접 정하려면 입력 요소에 id를 줍니다.

입력 요소는 기본 요소 그대로라 값과 검증은 [(ngModel)], reactive forms(formControlName), Signal Forms([formField])로 다룹니다.

ts
import { Component, signal } from '@angular/core'
import { FormsModule } from '@angular/forms'
import { KrdsFormGroup, KrdsInput } from '@krds.ui/angular'

@Component({
  selector: 'demo-form-group-basic',
  imports: [FormsModule, KrdsFormGroup, KrdsInput],
  template: `
    <krds-form-group label="이메일" hint="알림을 받을 이메일 주소를 입력해 주세요">
      <input krdsInput type="email" placeholder="example@korea.kr" [(ngModel)]="email" />
    </krds-form-group>
  `
})
export default class FormGroupBasic {
  readonly email = signal('')
}

TIP

폼 그룹은 입력 요소 하나를 위한 묶음입니다. 체크박스·라디오 버튼 여러 개는 <fieldset krdsCheckArea>와 <legend>로 묶습니다.

도움말 유형 ​

state를 error·success·information으로 지정하면 도움말이 각각 에러·성공·정보 메시지 스타일로 표시됩니다(기본값 default). error일 때는 입력 필드 테두리도 에러 색으로 바뀌고 입력 요소에 aria-invalid="true"가 붙습니다.

ts
import { Component } from '@angular/core'
import { KrdsFormGroup, KrdsInput } from '@krds.ui/angular'

@Component({
  selector: 'demo-form-group-hint-types',
  imports: [KrdsFormGroup, KrdsInput],
  template: `
    <div class="fieldset">
      <krds-form-group label="레이블" hint="도움말">
        <input krdsInput placeholder="플레이스홀더" />
      </krds-form-group>
      <krds-form-group label="레이블" hint="에러 메시지" state="error">
        <input krdsInput value="에러" />
      </krds-form-group>
      <krds-form-group label="레이블" hint="성공 메시지" state="success">
        <input krdsInput value="성공" />
      </krds-form-group>
      <krds-form-group label="레이블" hint="정보 메시지" state="information">
        <input krdsInput value="정보" />
      </krds-form-group>
    </div>
  `
})
export default class FormGroupHintTypes {}

검증 결과 보여 주기 ​

폼 그룹은 검증하지 않습니다. 폼 라이브러리의 검증 결과로 state와 hint를 정합니다. 아래 예제는 Signal Forms로 검증하고, 입력 필드를 한 번 떠난 뒤부터 오류 메시지를 보여 줍니다.

ts
import { Component, computed, signal } from '@angular/core'
import { FormField, email, form, required } from '@angular/forms/signals'
import { KrdsFormGroup, KrdsInput } from '@krds.ui/angular'

@Component({
  selector: 'demo-form-group-validation',
  imports: [FormField, KrdsFormGroup, KrdsInput],
  template: `
    <krds-form-group label="이메일" [hint]="hint()" [state]="showError() ? 'error' : 'default'">
      <input krdsInput type="email" placeholder="example@korea.kr" [formField]="signupForm.email" />
    </krds-form-group>
  `
})
export default class FormGroupValidation {
  readonly model = signal({ email: '' })
  readonly signupForm = form(this.model, path => {
    required(path.email, { message: '이메일을 입력해 주세요' })
    email(path.email, { message: '이메일 형식이 올바르지 않습니다' })
  })
  // 입력 필드를 한 번 떠난 뒤(touched)부터 오류를 보여 준다
  readonly showError = computed(() => this.signupForm.email().touched() && this.signupForm.email().invalid())
  readonly hint = computed(() =>
    this.showError() ? this.signupForm.email().errors()[0].message : '알림을 받을 이메일 주소를 입력해 주세요'
  )
}

입력 필드 안 버튼과 로딩 ​

withButton·deleteButton으로 입력 필드 안에 버튼을 두고, loading으로 스피너를 표시합니다. 예제는 텍스트 입력 필드에 있습니다.

KrdsFormGroup ​

선택자 krds-form-group

Inputs

이름타입기본값설명
labelstring-레이블
hintstring-도움말 (state에 따라 오류·성공·안내 문구)
state'default' | 'error' | 'success' | 'information''default'입력 상태
withButtonbooleanfalse입력 필드 안에 버튼을 둠 (비밀번호 보기·내용 삭제 등)
deleteButtonbooleanfalse값이 있을 때만 내용 삭제 버튼(.btn-delete-input)을 보임
loadingbooleanfalse입력 필드 안에 로딩 스피너 표시 (데이터를 불러오거나 검증하는 중)