컴포넌트

Editor

@inkio/editor — Editor

Notion-like 에디터. bubble menu, floating menu, slash command, block handle이 기본으로 활성화됩니다.


import { Editor } from '@inkio/editor';
import '@inkio/editor/style.css';

Prop	타입	설명
`content`	`string \| JSONContent`	초기 문서 (마운트 후 에디터가 상태 소유)
`editable`	`boolean`	편집 가능 여부 (기본값: `true`)
`placeholder`	`string`	빈 에디터 placeholder 텍스트
`locale`	`InkioLocaleInput`	로케일
`theme`	`'light' \| 'dark'`	색상 테마 (미지정 시 부모 환경을 따름)
`tabBehavior`	`'indent' \| 'default'`	Tab 키 동작 (기본값: `'indent'`). `'indent'`에서도 리스트 밖에서는 브라우저 기본 포커스 이동을 유지합니다
`onUpdate`	`(content: JSONContent) => void`	콘텐츠 변경 콜백
`onCreate`	`(editor: TiptapEditor) => void`	에디터 인스턴스 준비 콜백
`onError`	`InkioErrorHandler`	에러 핸들러
`ui`	`EditorUiOptions`	UI 옵션 (아래 참고)
`hashtagItems`	`(params: { query: string }) => HashTagItem[] \| Promise<HashTagItem[]>`	해시태그 제안
`mentionItems`	`(params: { query: string }) => MentionItem[] \| Promise<MentionItem[]>`	멘션 제안
`slashCommands`	`(query: string) => SlashCommandItem[] \| Promise<SlashCommandItem[]>`	슬래시 커맨드 오버라이드
`transformSlashCommands`	`SlashCommandTransform`	슬래시 커맨드 변환
`onWikiLinkClick`	`(href: string) => void`	위키 링크 클릭 핸들러
`onImageUpload`	`(file: File) => Promise<string \| { src: string }>`	이미지 업로드 핸들러. 반환 URL은 안전성 검사를 통과해야 저장됩니다
`imageBlock`	`Partial<ImageBlockOptions>`	ImageBlock 확장 옵션
`comment`	`CommentConfig`	댓글 기능 설정 (미지정 시 꺼짐)
`bookmark`	`false \| { onResolveBookmark? }`	북마크 기능 설정
`blockHandle`	`boolean`	블록 핸들 표시 여부 (읽기 전용에서는 표시·동작하지 않음)
`wikiLink`	`boolean`	위키 링크 활성화 여부
`table`	`boolean`	테이블 활성화 여부
`callout`	`boolean`	Callout 활성화 여부
`toggleList`	`boolean`	토글 리스트 활성화 여부
`extensions`	`ExtensionsInput`	확장 추가/교체

EditorUiOptions:

옵션	타입	설명
`showBubbleMenu`	`boolean`	bubble menu 표시 (기본값: `true`)
`showFloatingMenu`	`boolean`	floating menu 표시 (기본값: `true`)
`showTableMenu`	`boolean`	table menu 표시 (기본값: `true`)
`fill`	`boolean`	부모 높이를 채움
`autoresize`	`boolean`	콘텐츠 높이에 맞게 자동 조절
`bordered`	`boolean`	테두리 표시
`className`	`string`	루트 엘리먼트 클래스
`style`	`React.CSSProperties`	루트 엘리먼트 스타일
`messages`	`InkioMessageOverrides`	UI 메시지 오버라이드
`icons`	`Partial<InkioIconRegistry>`	아이콘 오버라이드
`bubbleMenu`	`Omit<BubbleMenuProps, 'editor'>`	BubbleMenu 세부 옵션
`floatingMenu`	`Omit<FloatingMenuProps, 'editor'>`	FloatingMenu 세부 옵션
`tableMenu`	`Omit<TableMenuProps, 'editor'>`	TableMenu 세부 옵션


export function EditorPage() {
  return (
    <Editor
      content="<p>Hello Inkio</p>"
      hashtagItems={({ query }) => [
        { id: query || 'inkio', label: `#${query || 'inkio'}` },
      ]}
      mentionItems={async ({ query }) => searchUsers(query)}
      onImageUpload={async (file) => URL.createObjectURL(file)}
      ui={{ showBubbleMenu: true, showFloatingMenu: true, fill: true }}
    />
  );
}

@inkio/simple — Editor

Classic toolbar-first 에디터. toolbar가 기본으로 활성화됩니다.


import { Editor } from '@inkio/simple';
import '@inkio/simple/style.css';

Prop	타입	설명
`content`	`string \| JSONContent`	초기 문서 (마운트 후 에디터가 상태 소유)
`editable`	`boolean`	편집 가능 여부
`placeholder`	`string`	placeholder 텍스트
`locale`	`InkioLocaleInput`	로케일
`theme`	`'light' \| 'dark'`	색상 테마 (미지정 시 부모 환경을 따름)
`tabBehavior`	`'indent' \| 'default'`	Tab 키 동작 (리스트 밖에서는 기본 포커스 이동 유지)
`onUpdate`	`(content: JSONContent) => void`	콘텐츠 변경 콜백
`onCreate`	`(editor: TiptapEditor) => void`	에디터 인스턴스 준비 콜백
`onError`	`InkioErrorHandler`	에러 핸들러
`onImageUpload`	`(file: File) => Promise<string \| { src: string }>`	이미지 업로드 핸들러. 반환 URL은 안전성 검사를 통과해야 저장됩니다
`imageBlock`	`Partial<ImageBlockOptions>`	ImageBlock 확장 옵션
`ui`	`SimpleEditorUiOptions`	UI 옵션
`extensions`	`ExtensionsInput`	확장 추가/교체

SimpleEditorUiOptions (@inkio/simple):

showToolbar (기본값: true), showBubbleMenu, showFloatingMenu, showTableMenu, fill, autoresize, bordered, className, style, messages, icons, toolbar, bubbleMenu, floatingMenu, tableMenu

패키지별 prop 비교

Prop	@inkio/editor	@inkio/simple
`content`	O	O
`onUpdate`, `onCreate`, `onError`	O	O
`ui.showToolbar`	- (항상 off)	O
`ui.showBubbleMenu`	O (기본 on)	O (기본 off)
`ui.showFloatingMenu`	O (기본 on)	O (기본 off)
`hashtagItems`	O	-
`mentionItems`	O	-
`slashCommands`	O	-
`onWikiLinkClick`	O	-
`comment`	O	-
`bookmark`	O	-
`blockHandle`	O	-
`wikiLink`	O	-
`onImageUpload`	O	O

Viewer

@inkio/editor — Viewer

@inkio/editor의 Viewer는 댓글(comment) 기능을 지원합니다.


import { Viewer } from '@inkio/editor';

Prop	타입	설명
`content`	`string \| JSONContent`	표시할 콘텐츠 (필수)
`locale`	`InkioLocaleInput`	로케일
`theme`	`'light' \| 'dark'`	색상 테마 (미지정 시 부모 환경을 따름)
`ui`	`{ className?, style?, bordered?, messages?, icons? }`	UI 옵션
`comment`	`ViewerCommentOptions`	댓글 표시 설정 (미지정 시 꺼짐)
`extensions`	`ExtensionsInput`	확장 추가/교체
`onCreate`	`(editor: TiptapEditor) => void`	에디터 인스턴스 준비 콜백

ViewerCommentOptions:


{
  getComments: (commentId: string) => CommentData | null;
  onReply?: (commentId: string, text: string) => void;
  onResolve?: (commentId: string) => void;
}


<Viewer
  content={content}
  comment={{
    getComments: (id) => store.getComment(id),
    onReply: (id, text) => store.reply(id, text),
    onResolve: (id) => store.resolve(id),
  }}
/>

@inkio/simple — Viewer


import { Viewer } from '@inkio/simple';

Prop	타입	설명
`content`	`string \| JSONContent`	표시할 콘텐츠 (필수)
`locale`	`InkioLocaleInput`	로케일
`theme`	`'light' \| 'dark'`	색상 테마 (미지정 시 부모 환경을 따름)
`ui`	`{ className?, style?, bordered?, messages?, icons? }`	UI 옵션
`extensions`	`ExtensionsInput`	확장 추가/교체

Viewer에서는 문서 편집 액션이 비활성화됩니다. 콜아웃 색상/아이콘 툴바와 블록 핸들은 표시되지 않고, 할 일(체크박스)·이미지 컨트롤도 상태를 바꾸지 않습니다. 댓글(reply/resolve)은 읽기 전용 인터랙션이라 그대로 동작합니다.

@inkio/core — StaticViewer (읽기 전용 경량 경로)

댓글·선택 같은 인터랙션이 필요 없는 목록/미리보기에는 StaticViewer를 사용하세요. Tiptap 인스턴스를 마운트하지 않고 살균된 정적 HTML만 렌더링하므로 <Viewer> 대비 번들이 가볍습니다.


import { StaticViewer } from '@inkio/core/static';

Prop	타입	설명
`content`	`string \| JSONContent`	표시할 콘텐츠 (필수)
`theme`	`'light' \| 'dark'`	색상 테마 (미지정 시 부모 환경을 따름)
`ui`	`{ className?, style?, bordered? }`	UI 옵션
`extensions`	`ExtensionsInput`	확장 추가/교체

locale/messages/icons/onCreate는 없습니다. 정적 렌더링에는 인터랙티브 UI가 없고 에디터 인스턴스가 존재하지 않기 때문입니다. 인터랙티브 읽기 전용(댓글 등)이 필요하면 <Viewer>를 사용하세요.

core 스키마에 없는 노드를 담은 콘텐츠(댓글·멘션·북마크 등 advanced 확장 타입)는 빈 셀로 폴백됩니다. 그런 콘텐츠를 정적으로 렌더링하려면 해당 스키마를 extensions로 전달하세요.

ToC (목차)

Inkio는 두 가지 목차 옵션을 제공합니다.

Option 1: TocBlock (인라인 블록)

@inkio/core에 기본 포함되는 인라인 목차 블록입니다. /toc 슬래시 커맨드로 에디터 안에 직접 삽입하며, 헤딩이 추가·수정·삭제되면 자동으로 업데이트됩니다. 배경·테두리 없는 Notion 스타일 미니멀 디자인입니다.

비활성화하려면 getExtensions에 tocBlock: false를 전달합니다:


import { getExtensions } from '@inkio/core';
 
const extensions = getExtensions({ tocBlock: false });

자세한 내용은 TocBlock 확장을 참고하세요.

Option 2: `<ToC>` 컴포넌트 (오버레이 미니맵)

에디터 오른쪽 가장자리에 Notion 스타일 미니맵 바를 표시하는 오버레이 컴포넌트입니다. 바에 마우스를 올리면 슬라이드 애니메이션과 함께 전체 헤딩 패널이 펼쳐집니다.

에디터를 감싸는 컨테이너에 position: relative를 설정하고, 그 안에 <ToC>를 배치합니다.


import { ToC } from '@inkio/editor';
// 또는
import { ToC } from '@inkio/core';

Prop	타입	기본값	설명
`source`	`TiptapEditor \| null`	-	에디터 인스턴스
`maxLevel`	`number`	`3`	포함할 최대 헤딩 레벨 (h1-h3)
`className`	`string`	-	루트 엘리먼트 클래스
`style`	`React.CSSProperties`	-	루트 엘리먼트 스타일


import { useState } from 'react';
import { Editor, ToC } from '@inkio/editor';
import '@inkio/editor/style.css';
 
function MyEditor() {
  const [editor, setEditor] = useState(null);
  return (
    <div style={{ position: 'relative' }}>
      <Editor onCreate={setEditor} />
      <ToC source={editor} />
    </div>
  );
}

헤딩 클릭 시 스크롤 오프셋을 조정하려면 CSS 변수를 사용하세요:


:root {
  --inkio-scroll-offset: 80px; /* sticky header 높이 등 */
}

CSS

파일	포함 내용	용도
`@inkio/editor/style.css`	전체 스타일 (advanced 프리셋 포함)	일반 사용
`@inkio/simple/style.css`	core 스타일만	classic 에디터
`@inkio/editor/minimal.css`	구조만 (색상·폰트 없음)	커스텀 테마
`@inkio/simple/minimal.css`	구조만	커스텀 테마

조합별 import 매트릭스

조합	import	비고
`@inkio/simple` 단독	`simple/style.css`	—
`@inkio/editor` 단독	`editor/style.css`	advanced 장식 포함
`core` + `advanced` 직접 조합	`core/style.css`	멘션 pill 등 advanced 장식은 `editor/style.css`에만 있음
`image-editor` (단독·연결 공통)	`image-editor/style.css`	자체 스타일시트 필수
`collab` (`CollabPresence`)	불필요	인라인 스타일만 사용
커스텀 테마	각 패키지의 `minimal.css` + `--inkio-*` 토큰 재정의	색상·폰트는 직접 정의

minimal.css는 레이아웃과 구조적 스타일만 포함합니다. 색상, 폰트, 배경 등은 직접 정의해야 합니다.


// 일반 사용
import '@inkio/editor/style.css';
 
// 커스텀 테마 (디자인 토큰을 직접 정의할 때)
import '@inkio/editor/minimal.css';

커스텀 범위 지도

대상	방법	비고
문구	`ui.messages`	타입별 override, `en*Messages`에서 출발
아이콘	`ui.icons`	`Partial<InkioIconRegistry>`, 일부만 교체 가능
색상·폰트·간격	CSS 변수 (`--inkio-*`)	`minimal.css` + 토큰 재정의
전체 테마	`theme` prop 또는 CSS	`'light'`/`'dark'`, 미지정 시 부모 추종
메뉴 구성	`ui.show*` + `toolbar`/`bubbleMenu` 세부 옵션	preset별 기본값 상이 (위 비교표)
에디터 동작	`extensions` 추가/교체	`ExtensionsInput` 규칙 준수

외부에서 값을 바꾸려면: onCreate로 받은 인스턴스의 editor.commands.setContent()를 쓰세요 (content prop은 초기값 전용).

바꿀 수 없는 것: StaticViewer의 인터랙션 (정적 렌더 전용).

공통 UI override

ui prop으로 UI 관련 옵션을 묶어 전달합니다.


import { Editor, type InkioMessageOverrides } from '@inkio/editor';
 
const messages: InkioMessageOverrides = {
  core: {
    suggestion: { empty: 'No matching items.' },
  },
};
 
export function Page() {
  return (
    <Editor
      ui={{
        messages,
        showBubbleMenu: true,
        showFloatingMenu: true,
        fill: true,
      }}
    />
  );
}

부모 높이를 기준으로 에디터를 채우려면 ui.fill을 사용합니다. 부모 컨테이너에 계산된 높이가 있어야 동작합니다.


<section style={{ height: '640px' }}>
  <Editor ui={{ fill: true }} />
</section>

기본 메시지 export


import { enCoreMessages } from '@inkio/editor';
import { enCommentMessages } from '@inkio/advanced';
import { enImageEditorMessages } from '@inkio/image-editor';