@neo4j-ndl/react
Version:
React implementation of Neo4j Design System
153 lines (132 loc) • 9.28 kB
Markdown
---
name: ndl-react
description: >-
Build and edit UI with the Neo4j Needle React design system
(-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 (-ndl/react)
> 📌 Shipped with `-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 `-ndl/react`; some live under the
`-ndl/react/next` and `-ndl/react/ai` subpaths (see the catalog).
- Prefer icons exported from `-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 `-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 `-ndl/react/next`.
Next-generation components, imported from the `-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 `-ndl/react/ai`.
Building blocks for AI chat / agent UIs, imported from the `-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 |