cmdk - GitLite

KO | EN

gitlite — search

#react #llm #golang #rust #deep-learning #linux #docker #nodejs #cli #kubernetes #vue #awesome-list #mcp #openai

cmdk

(★ 12,903)

빠르고 스타일이 없는 커맨드 메뉴 React 컴포넌트.

파일 탐색기

최종 버전 다운로드 (.zip)

- - test.yml
- FUNDING.yml
- pre-commit
- - command-score.ts
  - index.tsx
- package.json
- tsup.config.ts
- - _app.tsx
  - dialog.tsx
  - group.tsx
  - huge.tsx
  - index.tsx
  - item-advanced.tsx
  - item.tsx
  - keybinds.tsx
  - numeric.tsx
  - portal.tsx
  - props.tsx
- basic.test.ts
- dialog.test.ts
- group.test.ts
- item.test.ts
- keybind.test.ts
- next-env.d.ts
- numeric.test.ts
- package.json
- props.test.ts
- style.css
- tsconfig.json
- - index.ts
- - _app.tsx
  - _document.tsx
  - index.tsx
- - favicon.svg
  - grid.svg
  - inter-var-latin.woff2
  - line.svg
  - og.png
  - paco.png
  - rauno.jpeg
  - robots.txt
  - vercel.svg
- - globals.scss
  - index.module.scss
- .eslintrc.json
- .gitignore
- next-env.d.ts
- next.config.js
- package.json
- README.md
- tsconfig.json
- vercel.json
.gitignore
.prettierignore
.prettierrc.js
ARCHITECTURE.md
LICENSE.md
package.json
playwright.config.ts
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
tsconfig.json

🚀 설치 가이드

1. 코드 내려받기

git clone https://github.com/dip/cmdk

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd cmdk

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

pnpm install cmdk

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

$ pnpm install @radix-ui/react-popover

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

pnpm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

pnpm playwright install

이 명령어를 터미널에 그대로 입력해 실행하세요.

pnpm build

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![](./website/public/og.png)

# ⌘K [![cmdk minzip package size](https://img.shields.io/bundlephobia/minzip/cmdk)](https://www.npmjs.com/package/cmdk?activeTab=code) [![cmdk package version](https://img.shields.io/npm/v/cmdk.svg?colorB=green)](https://www.npmjs.com/package/cmdk)
⌘K는 접근 가능한 콤보박스로도 사용할 수 있는 명령어 메뉴 React 컴포넌트입니다. 아이템을 렌더링하면 자동으로 필터링하고 정렬해 줍니다. ⌘K는 완전히 조합 가능한 API를 지원하므로 [어떻게?](/ARCHITECTURE.md), 아이템을 다른 컴포넌트로 감싸거나 심지어 정적 JSX로도 사용할 수 있습니다.
## 설치
```bash
pnpm install cmdk
```
## 사용법
```tsx
import { Command } from 'cmdk'
const CommandMenu = () => {
return (

검색 결과가 없습니다.

a
b

c
Apple
)
}
```
또는 다이얼로그 안에서:
```tsx
import { Command } from 'cmdk'
const CommandMenu = () => {
const [open, setOpen] = React.useState(false)
// ⌘K를 누를 때 메뉴 토글
React.useEffect(() => {
const down = (e) => {
if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
e.preventDefault()
setOpen((open) => !open)
}
}
document.addEventListener('keydown', down)
return () => document.removeEventListener('keydown', down)
}, [])
return (

검색 결과가 없습니다.

a
b

c
Apple
)
}
```
## 구성 요소 및 스타일링
모든 구성 요소는 `ref`를 포함한 프롭스를 적절한 엘리먼트로 전달합니다. 각 구성 요소에는 스타일링에 사용할 수 있는 고유한 데이터 속성(`cmdk-`로 시작함)이 있습니다.
### Command `[cmdk-root]`
이를 렌더링하여 명령어 메뉴를 인라인으로 표시하거나, [Dialog](#dialog-cmdk-dialog-cmdk-overlay)를 사용하여 상위 컨텍스트에 렌더링할 수 있습니다. `value` 및 `onValueChange` 프롭스로 제어할 수 있습니다.
> \*\*참고\*\*
>
> 값은 항상 [trim()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/String/trim) 메서드로 앞뒤 공백이 제거됩니다.
```tsx
const [value, setValue] = React.useState('apple')
return (

Orange
Apple
)
```
각 아이템의 순위를 매기기 위해 호출되는 커스텀 `filter` 함수를 제공할 수 있습니다. 값의 공백은 제거된다는 점을 참고하세요.
```tsx
 {
if (value.includes(search)) return 1
return 0
}}
/>
```
필터 함수에 세 번째 인수인 `keywords`를 제공할 수도 있습니다. 키워드는 아이템 값의 별칭 역할을 하며, 아이템의 순위에도 영향을 줄 수 있습니다. 키워드 역시 공백이 제거됩니다.
```tsx
 {
const extendValue = value + ' ' + keywords.join(' ')
if (extendValue.includes(search)) return 1
return 0
}}
/>
```
또는 필터링과 정렬을 완전히 비활성화할 수 있습니다:
```tsx

{filteredItems.map((item) => {
return (
{item}
)
})}
```
`loop` prop을 설정하여 목록에서 방향키가 순환하도록 만들 수 있습니다 (끝에 도달하면 첫 번째 항목으로 돌아갑니다):
```tsx
```
### Dialog `[cmdk-dialog]` `[cmdk-overlay]`
Props는 [Command](#command-cmdk-root)로 전달됩니다. Radix UI의 Dialog 컴포넌트를 구성합니다. 오버레이는 항상 렌더링됩니다. 자세한 내용은 [Radix Documentation](https://www.radix-ui.com/docs/primitives/components/dialog)을 참조하세요. `open` 및 `onOpenChange` prop으로 제어할 수 있습니다.
```tsx
const [open, setOpen] = React.useState(false)
return (
...
)
```
Dialog가 포탈(portal)될 요소를 지정하기 위해 Radix UI의 Dialog Portal 컴포넌트로 전달되는 HTML 요소를 받는 `container` prop을 제공할 수 있습니다 (기본값은 `body`). 자세한 내용은 [Radix Documentation](https://www.radix-ui.com/docs/primitives/components/dialog#portal)을 참조하세요.
```tsx
const containerElement = React.useRef(null)
return (
<>
)
```
### Input `[cmdk-input]`
모든 prop은 내부 `input` 요소로 전달됩니다. `value` 및 `onValueChange` prop으로 제어할 수 있습니다.
```tsx
const [search, setSearch] = React.useState('')
return 
```
### List `[cmdk-list]`
아이템과 그룹을 포함합니다. `--cmdk-list-height` CSS 변수를 사용하여 높이에 애니메이션을 적용하세요.
```css
[cmdk-list] {
min-height: 300px;
height: var(--cmdk-list-height);
max-height: 500px;
transition: height 100ms ease;
}
```
뷰포트 가장자리 근처에서 아이템이 더 일찍 화면에 스크롤되도록 하려면 scroll-padding을 사용하세요:
```css
[cmdk-list] {
scroll-padding-block-start: 8px;
scroll-padding-block-end: 8px;
}
```
### Item `[cmdk-item]` `[data-disabled?]` `[data-selected?]`
포인터 진입 시 활성화되는 아이템입니다. 각 아이템에 고유한 `value`를 제공해야 하지만, 제공하지 않으면 `.textContent`에서 자동으로 유추됩니다.
```tsx
 console.log('Selected', value)}
// 제공된 텍스트 콘텐츠 덕분에 Value는 암시적으로 "apple"이 됩니다.
>
Apple
```
필터링을 돕기 위해 `keywords` prop을 제공할 수도 있습니다. 키워드의 공백은 자동으로 제거됩니다.
```tsx
Apple
```
```tsx
 console.log('Selected', value)}
// 제공된 텍스트 콘텐츠 덕분에 Value는 암시적으로 "apple"이 됩니다.
>
Apple
```
`forceMount` prop을 전달하여 필터링 여부와 관계없이 아이템이 항상 렌더링되도록 강제할 수 있습니다.
### Group `[cmdk-group]` `[hidden?]`
지정된 `heading` (`[cmdk-group-heading]`)과 함께 아이템들을 그룹화합니다.
```tsx
Apple
```
그룹은 DOM에서 언마운트되지 않고, 대신 뷰에서 숨기기 위해 `hidden` 속성이 적용됩니다. 이는 스타일링 시 유용할 수 있습니다.
`forceMount` prop을 전달하여 필터링 여부와 관계없이 그룹이 항상 렌더링되도록 강제할 수 있습니다.
### Separator `[cmdk-separator]`
검색어가 비어 있거나 `alwaysRender`가 true일 때 표시되며, 그 외에는 숨겨집니다.
### Empty `[cmdk-empty]`
검색 결과가 없을 때 자동으로 렌더링됩니다.
### Loading `[cmdk-loading]`
비동기 아이템을 로딩하는 동안 `progress`와 함께 조건부로 렌더링해야 합니다.
```tsx
const [loading, setLoading] = React.useState(false)
return {loading && 잠시만 기다려주세요…}
```
### `useCommandState(state => state.selectedField)`
[`useSyncExternalStore`](https://reactjs.org/docs/hooks-reference.html#usesyncexternalstore)를 구성하는 훅입니다. 명령 메뉴 상태의 일부(slice)를 반환하는 함수를 전달하여 해당 부분이 변경될 때마다 다시 렌더링하도록 합니다. 이 훅은 고급 사용 사례를 위해 제공되며 일반적으로 자주 사용되어서는 안 됩니다.
좋은 사용 사례는 다음과 같이 더 상세한 빈 상태(empty state)를 렌더링하는 것입니다:
```tsx
const search = useCommandState((state) => state.search)
return "{search}"에 대한 검색 결과가 없습니다.
```
## 예시 (Examples)
일반적인 사용 사례를 위한 코드 스니펫입니다.
### 중첩된 아이템 (Nested items)
종종 하나의 아이템을 선택하면 더 구체화된 아이템 세트와 함께 더 깊은 단계로 이동해야 합니다. 예를 들어 "테마 변경…"을 선택하면 새로운 아이템인 "어두운 테마"와 "밝은 테마"가 표시되어야 합니다. 우리는 이러한 아이템 세트를 "페이지"라고 부르며, 간단한 상태(state)로 구현할 수 있습니다:
```tsx
const ref = React.useRef(null)
const [open, setOpen] = React.useState(false)

```javascript
const [search, setSearch] = React.useState('')
const [pages, setPages] = React.useState([])
const page = pages[pages.length - 1]
return (
  <Box
    onKeyDown={(e) => {
      // Escape 키를 누르면 이전 페이지로 이동합니다
      // 검색어가 비어있을 때 Backspace 키를 누르면 이전 페이지로 이동합니다
      if (e.key === 'Escape' || (e.key === 'Backspace' && !search)) {
        e.preventDefault()
        setPages((pages) => pages.slice(0, -1))
      }
    }}
  >
```

```tsx
{!page && (
  <>
     setPages([...pages, 'projects'])}>Search projects…
     setPages([...pages, 'teams'])}>Join a team…
  </>
)}
{page === 'projects' && (
  <>
    Project A
    Project B
  </>
)}
{page === 'teams' && (
  <>
    Team 1
    Team 2
  </>
)}
)
```

### 검색 시 하위 항목 표시하기
검색할 때만 표시하고 싶은 중첩된 하위 항목이 있는 경우, 검색 상태를 기반으로 렌더링하세요:

```tsx
const SubItem = (props) => {
  const search = useCommandState((state) => state.search)
  if (!search) return null
  return <Command.Item {...props} />
}

return (
  <Command>
    <Command.Input />
    <Command.List>
      <Command.Item>Change theme…</Command.Item>
      <SubItem>Change theme to dark</SubItem>
      <SubItem>Change theme to light</SubItem>
    </Command.List>
  </Command>
)
```

### 비동기 결과
항목을 사용할 수 있게 되는 대로 렌더링합니다. 필터링과 정렬은 자동으로 처리됩니다.

```tsx
const [loading, setLoading] = React.useState(false)
const [items, setItems] = React.useState([])

React.useEffect(() => {
  async function getItems() {
    setLoading(true)
    const res = await api.get('/dictionary')
    setItems(res)
    setLoading(false)
  }
  getItems()
}, [])

return (
  <Command>
    <Command.Input />
    <Command.List>
      {loading && <Command.Loading>Fetching words…</Command.Loading>}
      {items.map((item) => {
        return (
          <Command.Item key={item}>
            {item}
          </Command.Item>
        )
      })}
    </Command.List>
  </Command>
)
```

### Popover 내부에서 사용하기
[Radix UI popover](https://www.radix-ui.com/docs/primitives/components/popover) 컴포넌트 사용을 권장합니다. ⌘K는 Radix UI Dialog 컴포넌트를 기반으로 하므로, 종속성을 공유하여 번들 크기를 줄일 수 있습니다.

```bash
$ pnpm install @radix-ui/react-popover
```

popover 콘텐츠 내부에 `Command`를 렌더링합니다:

```tsx
import * as Popover from '@radix-ui/react-popover'

return (
  <Popover.Root>
    <Popover.Trigger>Toggle popover</Popover.Trigger>
    <Popover.Content>
      <Command>
        <Command.Input />
        <Command.List>
          <Command.Item>Apple</Command.Item>
        </Command.List>
      </Command>
    </Popover.Content>
  </Popover.Root>
)
```

### 스타일시트 드롭인
스타일링의 시작점으로 바로 사용할 수 있는 전역 스타일시트를 찾을 수 있습니다. 예제는 [website/styles/cmdk](website/styles/cmdk)를 참고하세요.

## FAQ

**접근성이 지원되나요?** 네. Voice Over 및 Chrome DevTools로 레이블, aria 속성, DOM 순서를 테스트했습니다. [Dialog](#dialog-cmdk-dialog-cmdk-overlay)는 접근 가능한 Dialog 구현을 구성합니다.

**가상화(Virtualization)가 지원되나요?** 아니요. 하지만 2,000~3,000개의 항목까지는 성능이 좋습니다. 직접 가상화를 구현하려면 아래 내용을 읽어보세요.

**항목을 수동으로 필터링/정렬할 수 있나요?** 네. [Command](#command-cmdk-root)에 `shouldFilter={false}`를 전달하세요. 메모리 사용량과 성능이 더 좋아집니다. 이 방식으로 직접 가상화를 구현할 수 있습니다.

**React 18에서 안전한가요?** 네, 필수입니다. `useId` 및 `useSyncExternalStore` 같은 React 18 훅을 사용합니다.

**스타일이 지정되어 있지 않나요?** 네, 나열된 CSS 셀렉터를 사용하세요.

**하이드레이션 불일치(Hydration mismatch) 문제가 있나요?** 아니요, 코드 내의 버그일 가능성이 높습니다. 서버에서 `Command.Dialog`의 `open` prop이 `false`인지 확인하세요.

**React Strict Mode에서 안전한가요?** 네. 문제를 발견하면 이슈를 남겨주세요.

**이상하거나 잘못된 동작이 발생하나요?** `Command.Item`에 `key`와 고유한 `value`가 있는지 확인하세요.

**Concurrent mode에서 안전한가요?** 아마도요, 하지만 Concurrent mode는 아직 완전히 상용화되지 않았습니다. 수동 DOM 순서 지정과 같은 위험한 접근 방식을 사용합니다.

**React Server Component인가요?** 아니요, 클라이언트 컴포넌트입니다.

**⌘K를 자동으로 감지하나요?** 아니요, 단축키 컨텍스트를 완벽하게 제어할 수 있도록 직접 구현해야 합니다.

**React Native를 지원하나요?** 아니요, 지원 계획도 없습니다. React Native 버전을 제작하신다면 알려주세요. 여기에 저장소 링크를 추가해 드리겠습니다.

## 역사
조합 가능한(composable) combobox API가 가능한지 알아보기 위해 2019년 Paco([@pacocoursey](https://twitter.com/pacocoursey))가 작성했습니다. 2020년 Rauno([@raunofreiberg](https://twitter.com/raunofreiberg))가 Vercel 커맨드 메뉴 및 자동완성에 사용했습니다. 2022년에 더 간단하고 성능이 뛰어난 접근 방식으로 독립적으로 다시 작성되었습니다. Shu([@shuding\_](https://twitter.com/shuding\_))의 아이디어와 도움을 받았습니다.

[use-descendants](https://github.com/pacocoursey/use-descendants)는 2019년 버전에서 분리되었습니다.

## 테스트
먼저 종속성과 Playwright 브라우저를 설치합니다:

```bash
pnpm install
pnpm playwright install
```

그다음 라이브러리가 빌드되었는지 확인합니다:

```bash
pnpm build
```

그런 다음 실제 브라우저 엔진을 대상으로 로컬 빌드를 사용하여 테스트를 실행합니다:

```bash
pnpm test
```