# 내장·기본 제공 에디터 (Built-in Editors)

> 내장 text·checkbox와 기본 제공 Select·Date plugin의 설정, 값 변환, 헤더 제어와 아이콘 연결 방법을 설명합니다.

Source page: https://bgrid.axisj.com/learn/built-in-editors
Last reviewed: 2026-09-24
Topics: text-editor, checkbox-editor, checkbox-header, select-editor, date-editor, parseValue, formatValue
Related guides: editing, editor-icons, editor-plugins, editing-events
Related API: /api/props#columns, /api/props#editable

문자열 입력과 boolean·권한 값 토글은 내장 text·checkbox editor를, 정해진 값과 날짜 선택은 `beautiful-grid/editors`의 기본 plugin을 사용합니다. 기본 plugin은 별도 UI 프레임워크 의존성을 추가하지 않습니다.

## Checkbox와 헤더 일괄 제어

```tsx
{
  key: 'approved',
  label: '승인 권한',
  width: 150,
  align: 'center',
  editable: true,
  editor: {
    type: 'checkbox',
    header: { ariaLabel: '승인 권한 전체 선택' },
    ariaLabel: ({ values }) => `${values.orderCode} 승인 권한`,
    label: ({ value }) => (value ? '허용' : '차단'),
    disabled: ({ values }) => values.locked,
  },
}
```

`header`를 켜면 헤더 checkbox가 선택 가능 행의 전체 선택·해제를 제어하고, 일부만 선택되었을 때 `indeterminate` 상태를 표시합니다. 현재 필터나 페이지로 Grid에 들어온 행만 대상으로 하며 `disabled`가 `true`인 셀과 삭제 상태 행은 상태 계산과 변경 대상에서 제외합니다.

기본 저장 값은 `true`와 `false`입니다. 서버 모델이 다른 값을 사용하면 `trueValue: 'Y'`, `falseValue: 'N'`처럼 매핑할 수 있습니다. 활성 셀에서는 Space, Enter 또는 F2로 값을 토글할 수 있습니다. 셀과 헤더 변경도 `onChangeValue` 검증을 거쳐 변경된 행마다 `onChangeData`를 호출하며, 이때 `meta.source`는 `'checkbox'`입니다.

## Text

```tsx
{
  key: 'quantity',
  editable: true,
  editor: {
    type: 'text',
    inputProps: { inputMode: 'numeric', autoComplete: 'off' },
    formatValue: value => String(value ?? ''),
    parseValue: text => {
      const value = Number(text);
      if (!Number.isFinite(value)) throw new Error('숫자를 입력하세요.');
      return value;
    },
  },
}
```

`parseValue`가 예외를 던지면 저장하지 않고 editor를 유지하며 `aria-invalid="true"`가 설정됩니다. `commitOnBlur: false`이면 외부 포커스 이동 시 저장하지 않고 취소합니다.

## Select와 Date

```tsx
const statusEditor = createSelectEditorPlugin<Order, Order['status']>({
  id: 'order-status',
  options: [
    { value: 'ready', label: '준비' },
    { value: 'done', label: '완료' },
  ],
});

const dateEditor = createDateEditorPlugin<Order>({
  id: 'delivery-date',
  min: '2026-01-01',
  max: '2026-12-31',
});
```

factory는 컴포넌트 바깥이나 `useMemo` 안에서 한 번만 생성하세요. 컬럼 렌더마다 새 plugin 객체를 만들면 입력 컴포넌트가 다시 마운트될 수 있습니다.

기본 Select는 셀 또는 아이콘 클릭으로 editor가 마운트되면 네이티브 옵션 picker를 즉시 엽니다. 자동 열기를 원하지 않으면 factory에 `openOnMount: false`를 지정할 수 있습니다.

기본 Date는 셀 본문을 클릭하면 숫자 날짜 입력만 활성화하고, `editorIcon`을 클릭해서 진입한 경우에만 네이티브 달력 picker를 엽니다. 편집 플러그인은 `activation` 값(`'cell' | 'editorIcon'`)으로 두 진입 경로를 구분할 수 있습니다.

```tsx
{
  key: 'status',
  editable: true,
  editTrigger: 'click',
  editor: statusEditor,
  editorIcon: { render: <ChevronDownIcon />, ariaLabel: '상태 선택' },
}
```

아이콘의 모양은 editor 종류로 자동 추론하지 않습니다. 제품 디자인 시스템에 맞는 아이콘을 `editorIcon.render`로 명시합니다.

## 앱의 UI 라이브러리를 그대로 사용하기

내장 editor보다 풍부한 picker나 애플리케이션과 동일한 디자인이 필요하다면 공식 UI 통합을 사용하세요. BeautifulGrid는 Ant Design, Shadcn UI, MUI, Mantine용 editor plugin을 제공하며 popup portal과 저장·취소 수명주기를 미리 연결해 둡니다.

[공식 에디터 플러그인 비교와 설치 방법 보기 →](/plugins)