---
name: ndl-react
description: >-
  Build and edit UI with the Neo4j Needle React design system
  (@neo4j-ndl/react). Use when adding, composing, or modifying Needle components
  in a React app. Provides per-component props, accessibility requirements, and
  runnable usage examples. Works with any agent that supports skills (Cursor,
  Claude, etc.).
---

# Neo4j Needle (@neo4j-ndl/react)

> 📌 Shipped with `@neo4j-ndl/react`. Once installed into your repo (e.g. via
> `npx skills add`) this folder is detached from the package — the installed
> package (TypeScript types in `node_modules/@neo4j-ndl/react`) is the source of
> truth.

Use Neo4j Needle components instead of hand-rolling equivalent UI.

## Setup

- Import the base stylesheet once at the app root (if not already wired):
  `import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';`
- Import components from `@neo4j-ndl/react`; some live under the
  `@neo4j-ndl/react/next` and `@neo4j-ndl/react/ai` subpaths (see the catalog).
- Prefer icons exported from `@neo4j-ndl/react/icons` (e.g.
  `MagnifyingGlassIconOutline`) for design-system parity.

## Rules

- **Never hallucinate props.** Before using any prop — including common-sounding
  ones like `size`, `tone`, or `shadow` — confirm it appears in the component's
  doc here or in the package's TypeScript types. Do not assume APIs from other
  libraries (MUI, Radix, Chakra). If something is unclear, ask the user — or when
  running unattended, prefer the TypeScript types and omit the uncertain prop
  rather than guessing.
- These docs are the primary source for props, accessibility, and examples. The
  package's `.d.ts` type contract is authoritative: if the types disagree with
  these docs, the **types win**. Do not reverse-engineer behavior from the
  compiled implementation source in `node_modules`.
- Pass native HTML attributes, `aria-*`, and `data-*` via the `htmlAttributes`
  prop, only where the component's doc says so.
- Compound components are exposed as subcomponents (e.g. `Tooltip.Trigger`,
  `Tooltip.Content`). Follow each component's own doc — don't assume one
  component's compound shape matches another's.
- Follow the accessibility guidance in each component's doc; don't strip built-in
  roles or keyboard behavior.

## How to use this skill

1. Find the component in the catalog below to get its docs file and import path.
2. Read `components/<file>` for that component's props, accessibility
   requirements, and runnable examples; prefer those examples.

## Components

Import from `@neo4j-ndl/react`.

| Component | Docs | Accessibility | Examples |
|-----------|------|---------------|----------|
| `Accordion` | [components/accordion.md](components/accordion.md) | ✅ | 6 |
| `Avatar` | [components/avatar.md](components/avatar.md) | ✅ | 7 |
| `Banner` | [components/banner.md](components/banner.md) | ✅ | 6 |
| `Box` | [components/box.md](components/box.md) |  | 1 |
| `Breadcrumbs` | [components/breadcrumbs.md](components/breadcrumbs.md) | ✅ | 4 |
| `Checkbox` | [components/checkbox.md](components/checkbox.md) | ✅ | 9 |
| `CleanIconButton` | [components/clean-icon-button.md](components/clean-icon-button.md) | ✅ | 8 |
| `ClipboardButton` | [components/clipboard-button.md](components/clipboard-button.md) |  | 7 |
| `Code` | [components/code.md](components/code.md) | ✅ | 2 |
| `CodeBlock` | [components/code-block.md](components/code-block.md) |  | 8 |
| `ColorPicker` | [components/color-picker.md](components/color-picker.md) |  | 3 |
| `ConditionalWrap` | [components/conditional-wrap.md](components/conditional-wrap.md) |  | 1 |
| `DataGrid` | [components/data-grid.md](components/data-grid.md) |  | 20 |
| `DatePicker` | [components/date-picker.md](components/date-picker.md) | ✅ | 14 |
| `Dialog` | [components/dialog.md](components/dialog.md) | ✅ | 7 |
| `DismissibleTag` | [components/dismissible-tag.md](components/dismissible-tag.md) |  | 4 |
| `Divider` | [components/divider.md](components/divider.md) |  | 3 |
| `Drawer` | [components/drawer.md](components/drawer.md) | ✅ | 8 |
| `DropdownButton` | [components/dropdown-button.md](components/dropdown-button.md) |  | 7 |
| `Dropzone` | [components/dropzone.md](components/dropzone.md) |  | 6 |
| `FilledButton` | [components/filled-button.md](components/filled-button.md) |  | 0 |
| `Flex` | [components/flex.md](components/flex.md) |  | 1 |
| `GraphLabel` | [components/graph-label.md](components/graph-label.md) |  | 7 |
| `IconButton` | [components/icon-button.md](components/icon-button.md) | ✅ | 7 |
| `IconButtonArrayComponent` | [components/icon-button-array.md](components/icon-button-array.md) |  | 5 |
| `InlineEdit` | [components/inline-edit.md](components/inline-edit.md) | ✅ | 9 |
| `Kbd` | [components/kbd.md](components/kbd.md) | ✅ | 2 |
| `LoadingBar` | [components/loading-bar.md](components/loading-bar.md) |  | 2 |
| `LoadingSpinner` | [components/loading-spinner.md](components/loading-spinner.md) | ✅ | 2 |
| `Logo` | [components/logo.md](components/logo.md) |  | 3 |
| `Menu` | [components/menu.md](components/menu.md) | ✅ | 13 |
| `Modal` | [components/modal.md](components/modal.md) | ✅ | 0 |
| `OutlinedButton` | [components/outlined-button.md](components/outlined-button.md) |  | 0 |
| `Popover` | [components/popover.md](components/popover.md) | ✅ | 6 |
| `ProgressBar` | [components/progress-bar.md](components/progress-bar.md) | ✅ | 3 |
| `Radio` | [components/radio.md](components/radio.md) | ✅ | 7 |
| `ReadOnlyTag` | [components/read-only-tag.md](components/read-only-tag.md) |  | 4 |
| `SegmentedControl` | [components/segmented-control.md](components/segmented-control.md) | ✅ | 5 |
| `Select` | [components/select.md](components/select.md) |  | 13 |
| `SelectIconButton` | [components/select-icon-button.md](components/select-icon-button.md) |  | 4 |
| `SelectableTag` | [components/selectable-tag.md](components/selectable-tag.md) |  | 6 |
| `SideNavigation` | [components/side-navigation.md](components/side-navigation.md) |  | 4 |
| `Skeleton` | [components/skeleton.md](components/skeleton.md) |  | 5 |
| `Slider` | [components/slider.md](components/slider.md) | ✅ | 8 |
| `Spotlight` | [components/spotlight.md](components/spotlight.md) | ✅ | 9 |
| `StatusIndicator` | [components/status-indicator.md](components/status-indicator.md) | ✅ | 1 |
| `StatusLabel` | [components/status-label.md](components/status-label.md) |  | 4 |
| `Switch` | [components/switch.md](components/switch.md) | ✅ | 7 |
| `Tabs` | [components/tabs.md](components/tabs.md) | ✅ | 7 |
| `Tag` | [components/tag.md](components/tag.md) |  | 2 |
| `TextArea` | [components/text-area.md](components/text-area.md) | ✅ | 8 |
| `TextButton` | [components/text-button.md](components/text-button.md) |  | 0 |
| `TextInput` | [components/text-input.md](components/text-input.md) | ✅ | 16 |
| `TextLink` | [components/text-link.md](components/text-link.md) | ✅ | 5 |
| `TimePicker` | [components/time-picker.md](components/time-picker.md) |  | 4 |
| `TimeZonePicker` | [components/timezone-picker.md](components/timezone-picker.md) |  | 9 |
| `Tooltip` | [components/tooltip.md](components/tooltip.md) | ✅ | 13 |
| `TreeView` | [components/tree-view.md](components/tree-view.md) |  | 3 |
| `Typography` | [components/typography.md](components/typography.md) |  | 3 |
| `Wizard` | [components/wizard.md](components/wizard.md) |  | 5 |

## Next components

Import from `@neo4j-ndl/react/next`.

Next-generation components, imported from the `@neo4j-ndl/react/next` subpath. A `next` component may share a name with a stable one (e.g. `TreeView`) but is a **distinct** implementation with its own API — import it from this subpath, and do not mix it with the same-named default component.

| Component | Docs | Accessibility | Examples |
|-----------|------|---------------|----------|
| `TreeView` | [components/next/tree-view.md](components/next/tree-view.md) | ✅ | 8 |

## AI components

Import from `@neo4j-ndl/react/ai`.

Building blocks for AI chat / agent UIs, imported from the `@neo4j-ndl/react/ai` subpath.

| Component | Docs | Accessibility | Examples |
|-----------|------|---------------|----------|
| `CodePreview` | [components/ai/code-preview.md](components/ai/code-preview.md) |  | 4 |
| `FileTag` | [components/ai/file-tag.md](components/ai/file-tag.md) |  | 3 |
| `ImageTag` | [components/ai/image-tag.md](components/ai/image-tag.md) |  | 3 |
| `MoreFilesComponent` | [components/ai/more-files.md](components/ai/more-files.md) |  | 1 |
| `Presence` | [components/ai/presence.md](components/ai/presence.md) |  | 2 |
| `Preview` | [components/ai/preview.md](components/ai/preview.md) |  | 9 |
| `Prompt` | [components/ai/prompt.md](components/ai/prompt.md) |  | 6 |
| `Reasoning` | [components/ai/reasoning.md](components/ai/reasoning.md) |  | 1 |
| `Response` | [components/ai/response.md](components/ai/response.md) |  | 7 |
| `Suggestion` | [components/ai/suggestion.md](components/ai/suggestion.md) |  | 4 |
| `Thinking` | [components/ai/thinking.md](components/ai/thinking.md) |  | 2 |
| `ToolCall` | [components/ai/tool-call.md](components/ai/tool-call.md) |  | 2 |
| `UserBubbleComponent` | [components/ai/user-bubble.md](components/ai/user-bubble.md) |  | 4 |