@ehfuse/mui-form-controls

MUI 기반 폼 컨트롤과 텍스트 필드 컴포넌트 모음

컴포넌트

| 컴포넌트 | 설명 | 문서 | | ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------- | | AddressTextField | 다음 우편번호 API 연동 주소 검색 필드 | API | | Autocomplete | 자동완성 기능이 있는 입력 필드 | API | | BizNumTextField | 사업자등록번호 입력 필드 (검증, 복사 기능) | API | | CardNumTextField | 카드번호 입력 필드 (마스킹, 브랜드 감지, 로고 아이콘) | API | | ClearTextField | 클리어 버튼이 있는 기본 텍스트 필드 | API | | DateRange | 날짜 범위 입력 필드 (시작일, 종료일) | API | | DateTextField | 달력 팝업, 다양한 날짜 포맷, 공휴일 표시 지원 날짜 필드 | API | | DateTimeTextField | 날짜 + 시간 입력 필드 | API | | EmailTextField | 도메인 자동완성, 유효성 검사 기능이 있는 이메일 필드 | API | | JuminTextField | 주민등록번호 입력 필드 (마스킹, 정보 추출) | API | | NumberField | 숫자 입력 (증감 버튼 포함) | API | | NumberSpinner | 숫자 스피너 | API | | NumberTextField | 천 단위 구분자, 소수점, 음수 지원하는 숫자 필드 | API | | PasswordTextField | 비밀번호 보기/숨기기 토글, 유효성 검사 기능이 있는 비밀번호 필드 | API | | PhoneTextField | 자동 포맷팅, prefix 고정 기능이 있는 전화번호 필드 | API | | SearchTextField | 클리어 버튼, 로딩 상태, 디바운스 기능이 있는 검색 필드 | API | | TextArea | 여러 줄 텍스트 입력 필드 | API | | TextField | MUI TextField 래퍼 (폼 통합) | API | | TimeTextField | 시간 입력 필드 (자동 포맷팅, 시간 범위 제한) | API | | VerificationCodeTextField | 인증번호 입력 필드 (숫자/영문/혼합) | API |

폼 컨트롤 (Form Controls)

키보드 입력이 필요한 컴포넌트는 위 "컴포넌트"에, 마우스 조작만으로 선택/토글하는 컴포넌트는 여기서 분리해 정리했습니다.

| 컴포넌트 | 설명 | 문서 | | --------------------- | ------------------------------------------------------------ | ----------------------------------------- | | ButtonGroup | 버튼 그룹 컴포넌트 | API | | Checkbox | MUI Checkbox 래퍼 (폼 통합) | API | | LabelSelect | MUI Select 기반 선택 필드 (권장: 라벨 포함, form 바인딩) | API | | RadioGroup | MUI RadioGroup 래퍼 (폼 통합) | API | | Rating | 평점 입력 컴포넌트 | API | | Slider | MUI Slider 래퍼 (폼 통합) | API | | Stepper | 스텝 진행 표시 컴포넌트 | API | | Switch | MUI Switch 래퍼 (폼 통합) | API | | ToggleButton | 토글 버튼 컴포넌트 | API | | ToggleButtonGroup | 옵션 기반 토글 그룹 필드 (ToggleButtonGroup + form 바인딩) | API |

훅 (Hooks)

| 훅 | 설명 | 문서 | | -------------------------- | --------------------------------------------------- | ---------------------------------------------- | | useKoreanHolidays | 단일 연도의 한국 공휴일을 조회하는 커스텀 훅 | API | | useKoreanHolidaysRange | 여러 연도의 한국 공휴일을 한번에 조회하는 커스텀 훅 | API |

설치

npm install @ehfuse/mui-form-controls

AddressTextField를 사용할 때만 다음 우편번호 의존성을 추가로 설치합니다.

npm install react-daum-postcode

필수 의존성

{
    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0",
    "@mui/material": "^5.0.0 || ^6.0.0 || ^7.0.0",
    "@mui/icons-material": "^5.0.0 || ^6.0.0 || ^7.0.0",
    "@emotion/react": "^11.0.0",
    "@emotion/styled": "^11.0.0",
    "@ehfuse/overlay-scrollbar": "^1.0.0"
}

빠른 시작

import {
  SearchTextField,
  ClearTextField,
  PasswordTextField,
  PhoneTextField,
  EmailTextField,
  NumberTextField,
  JuminTextField,
  BizNumTextField,
  CardNumTextField,
  VerificationCodeTextField,
  DateTextField,
  TimeTextField,
  DateTimeTextField,
  TextField,
  Rating,
  ToggleButton,
  ToggleButtonGroup,
  ButtonGroup,
  Stepper,
  NumberField,
  NumberSpinner,
  LabelSelect,
  Autocomplete,
  Checkbox,
  RadioGroup,
  Switch,
  ToggleButtonGroup,
  Slider,
  DateRange,
  TextArea,
  useKoreanHolidays,
  useKoreanHolidaysRange,
} from '@ehfuse/mui-form-controls';

import { AddressTextField } from '@ehfuse/mui-form-controls/address';

// 검색 필드
<SearchTextField
  value={search}
  onChange={(e) => setSearch(e.target.value)}
  searchIcon
  loading={isSearching}
/>

// 비밀번호 필드
<PasswordTextField
  value={password}
  onChange={(e) => setPassword(e.target.value)}
  showToggle
/>

// 전화번호 필드
<PhoneTextField
  value={phone}
  onChange={(e) => setPhone(e.target.value)}
  prefix="010"
/>

// 이메일 필드 (forma 호환)
<EmailTextField
  name="email"
  value={email}
  onChange={handleFormChange}
  extraDomains={["mycompany.com"]}
/>

// 숫자 필드
<NumberTextField
  value={amount}
  onChange={(e) => setAmount(e.target.value)}
  prefix="₩"
  suffix="원"
/>

// 날짜 필드
<DateTextField
  value={date}
  onChange={(e) => setDate(e.target.value)}
  format="YYYY.MM.DD"
  selectedColor="secondary.main"
/>

// 주소 필드
<AddressTextField
  value={address}
  onChange={setAddress}
/>

// 주민등록번호 필드
<JuminTextField
  value={jumin}
  onChange={setJumin}
  mask
/>

// 사업자등록번호 필드
<BizNumTextField
  value={bizNum}
  onChange={setBizNum}
  validate
  copyIcon
/>

// 카드번호 필드
<CardNumTextField
  value={cardNum}
  onChange={(e) => setCardNum(e.target.value)}
  onCardBrandChange={(brand) => console.log('카드 브랜드:', brand)}
/>

// 인증번호 필드
<VerificationCodeTextField
  value={code}
  onChange={setCode}
  length={6}
  type="numeric"
  onComplete={(code) => console.log('완료:', code)}
/>

// 시간 필드
<TimeTextField
  value={time}
  onChange={(e) => setTime(e.target.value)}
  format="HH:mm"
  minTime="09:00"
  maxTime="18:00"
/>

// 선택 필드 (권장: LabelSelect)
<LabelSelect
  name="category"
  label="카테고리"
  form={form}
  options={[
    { value: 'a', label: 'A' },
    { value: 'b', label: 'B' },
  ]}
/>

// 자동완성 필드
<Autocomplete
  name="department"
  label="부서"
  form={form}
  options={[
    { value: 'dev', label: '개발' },
    { value: 'design', label: '디자인' },
  ]}
/>

// 날짜 범위
<DateRange
  form={form}
  startName="startDate"
  endName="endDate"
  startLabel="시작일"
  endLabel="종료일"
/>

// 텍스트 에어리어
<TextArea
  name="memo"
  label="메모"
  form={form}
  minRows={4}
/>

선택 입력은 예제/문서 기준으로 LabelSelect를 사용합니다.

Boolean 필드 표준 패턴

Switch를 boolean 입력의 기본 form-binding 컴포넌트로 사용합니다.

import { Switch } from "@ehfuse/mui-form-controls";

// 1) 단일 스위치 (라벨 없음)
<Switch form={form} name="deceased_disability_certificate" />

// 2) 라벨 포함 스위치 (권장)
<Switch
  form={form}
  name="deceased_disability_certificate"
  label="장애인 증명서 제출"
/>

// 3) readOnly / disabled
<Switch
  form={form}
  name="deceased_disability_certificate"
  label="수정 불가 항목"
  readonly
/>
<Switch
  form={form}
  name="deceased_disability_certificate"
  label="비활성 항목"
  disabled
/>

Toggle 그룹 표준 패턴

import { ToggleButtonGroup } from "@ehfuse/mui-form-controls";

<ToggleButtonGroup
    form={form}
    name="contractor_gender"
    exclusive
    options={[
        { label: "남성", value: "M" },
        { label: "여성", value: "F" },
    ]}
    onDeselect="clear"
    fullWidth
    size="small"
/>;

문서 / Documentation

• 한국어 문서
• English Documentation

라이선스 / License

MIT © 김영진 (Kim Young Jin)