React Component Writing Guide
Styling
| Scenario |
Approach |
| Most cases |
createStaticStyles + cssVar.* (zero-runtime, module-level) |
| Simple one-off |
Inline style attribute |
Truly dynamic (JS color fns like readableColor/chroma) |
createStyles + token — last resort |
Component Priority
src/components — project-specific reusable components@lobehub/ui/base-ui — headless primitives. If the component lives here, use it. Do NOT import the same-named root export.@lobehub/ui — higher-level / antd-wrapping components (only when no base-ui equivalent)- antd — only when neither base-ui nor
@lobehub/ui root provides it
- Custom implementation — true last resort
If unsure about available components, search existing code or check node_modules/@lobehub/ui/es/index.mjs and node_modules/@lobehub/ui/es/base-ui/.
@lobehub/ui/base-ui — always prefer for these
| Component |
Import |
Alert (+ AlertProps) |
import { Alert, type AlertProps } from '@lobehub/ui/base-ui'; |
Select (+ SelectProps, SelectOption) |
import { Select } from '@lobehub/ui/base-ui'; |
Modal (imperative API) |
import { createModal, confirmModal, useModalContext, type ModalInstance } from '@lobehub/ui/base-ui'; |
DropdownMenu |
import { DropdownMenu } from '@lobehub/ui/base-ui'; |
ContextMenu |
import { ContextMenu } from '@lobehub/ui/base-ui'; |
Popover |
import { Popover } from '@lobehub/ui/base-ui'; |
ScrollArea |
import { ScrollArea } from '@lobehub/ui/base-ui'; |
Switch |
import { Switch } from '@lobehub/ui/base-ui'; |
Toast |
import { Toast } from '@lobehub/ui/base-ui'; |
FloatingSheet |
import { FloatingSheet } from '@lobehub/ui/base-ui'; |
Drawer |
import { Drawer } from '@lobehub/ui/base-ui'; |
For Modal specifically, see the dedicated modal skill — use the imperative createModal({ content: … }) pattern over the legacy <Modal open … /> declarative pattern. base-ui has its own ModalHost already mounted in SPAGlobalProvider.
Common slip: import { Select } from '@lobehub/ui' looks fine but it's the antd-backed Select. Use base-ui Select. Same for Modal, DropdownMenu, etc.
@lobehub/ui root — use when base-ui has no equivalent
| Category |
Components |
| General |
ActionIcon, ActionIconGroup, Block, Button, Icon |
| Data Display |
Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip |
| Data Entry |
CodeEditor, CopyButton, EditableText, Form, Input, InputPassword, SearchBar, TextArea |
| Layout |
Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow |
| Navigation |
Burger, Menu, SideNav, Tabs |
State
Keep transient state in its smallest useful owner. Extract a custom hook when state transitions and handlers obscure rendering or form a reusable unit; do not extract solely because a component has a particular number of hooks.
Split a component only to establish a real state, reuse, render-update, or mountable-capability boundary. Do not split solely to make files smaller. Decomposing a heavy domain feature into host-assembled atoms is owned by compose-atoms.
Render Performance and Memoization
Treat memo, useMemo, and useCallback as opt-in optimizations, not default component wrappers. Before adding one, identify the actual rerender boundary and prefer structural fixes:
- Split at the update boundary.
- Move transient state to its smallest owner.
- Use narrow Zustand selectors and avoid broad subscriptions.
Do not memoize prop-free or trivially rendered components, or a component that normally receives new objects, arrays, functions, or JSX children. Do not use memoization to compensate for state held too high in the tree.
Use memoization only when the subtree is demonstrably expensive or frequently repeated, its relevant inputs are stable during normal parent renders, and profiling or a concrete render-path analysis identifies the avoided work. State that reason in the implementation summary or PR.
Layout
Use Flexbox and Center from @lobehub/ui. See references/layout-kit.md for full props and examples.
- Use
gap instead of margin for spacing between flex children
- Use
flex={1} to fill available space
- Nest Flexbox for complex layouts; set
overflow: 'auto' for scrollable regions
Related Skills
ux: loading visuals and user-facing interaction design. Do not use antd Spin / <Spin />.modal: imperative base-ui modal patterns.spa-routes: SPA navigation, route ownership, router configuration, and .desktop variants.compose-atoms: split a heavy domain feature into mountable capability atoms; each host imports only what it mounts.zustand: store structure and selector conventions.
1---2name: react3description: Use for TSX components, UI libraries, styling, state locality, layout, render performance and memoization.4---56# React Component Writing Guide78## Styling910| Scenario | Approach |11| ---------------------------------------------------------- | -------------------------------------------------------------- |12| Most cases | `createStaticStyles` + `cssVar.*` (zero-runtime, module-level) |13| Simple one-off | Inline `style` attribute |14| Truly dynamic (JS color fns like `readableColor`/`chroma`) | `createStyles` + `token` — **last resort** |1516## Component Priority17181. **`src/components`** — project-specific reusable components192. **`@lobehub/ui/base-ui`** — headless primitives. **If the component lives here, use it. Do NOT import the same-named root export.**203. **`@lobehub/ui`** — higher-level / antd-wrapping components (only when no base-ui equivalent)214. **antd** — only when neither base-ui nor `@lobehub/ui` root provides it225. **Custom implementation** — true last resort2324If unsure about available components, search existing code or check `node_modules/@lobehub/ui/es/index.mjs` and `node_modules/@lobehub/ui/es/base-ui/`.2526### `@lobehub/ui/base-ui` — always prefer for these2728| Component | Import |29| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |30| `Alert` (+ `AlertProps`) | `import { Alert, type AlertProps } from '@lobehub/ui/base-ui';` |31| `Select` (+ `SelectProps`, `SelectOption`) | `import { Select } from '@lobehub/ui/base-ui';` |32| `Modal` (imperative API) | `import { createModal, confirmModal, useModalContext, type ModalInstance } from '@lobehub/ui/base-ui';` |33| `DropdownMenu` | `import { DropdownMenu } from '@lobehub/ui/base-ui';` |34| `ContextMenu` | `import { ContextMenu } from '@lobehub/ui/base-ui';` |35| `Popover` | `import { Popover } from '@lobehub/ui/base-ui';` |36| `ScrollArea` | `import { ScrollArea } from '@lobehub/ui/base-ui';` |37| `Switch` | `import { Switch } from '@lobehub/ui/base-ui';` |38| `Toast` | `import { Toast } from '@lobehub/ui/base-ui';` |39| `FloatingSheet` | `import { FloatingSheet } from '@lobehub/ui/base-ui';` |40| `Drawer` | `import { Drawer } from '@lobehub/ui/base-ui';` |4142For Modal specifically, see the dedicated **modal** skill — use the imperative `createModal({ content: … })` pattern over the legacy `<Modal open … />` declarative pattern. base-ui has its own `ModalHost` already mounted in `SPAGlobalProvider`.4344> Common slip: `import { Select } from '@lobehub/ui'` looks fine but it's the antd-backed Select. Use base-ui Select. Same for `Modal`, `DropdownMenu`, etc.4546### `@lobehub/ui` root — use when base-ui has no equivalent4748| Category | Components |49| ------------ | ------------------------------------------------------------------------------------- |50| General | ActionIcon, ActionIconGroup, Block, Button, Icon |51| Data Display | Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip |52| Data Entry | CodeEditor, CopyButton, EditableText, Form, Input, InputPassword, SearchBar, TextArea |53| Layout | Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow |54| Navigation | Burger, Menu, SideNav, Tabs |5556## State5758Keep transient state in its smallest useful owner. Extract a custom hook when state transitions and handlers obscure rendering or form a reusable unit; do not extract solely because a component has a particular number of hooks.5960Split a component only to establish a real state, reuse, render-update, or mountable-capability boundary. Do not split solely to make files smaller. Decomposing a heavy domain feature into host-assembled atoms is owned by **`compose-atoms`**.6162## Render Performance and Memoization6364Treat `memo`, `useMemo`, and `useCallback` as opt-in optimizations, not default component wrappers. Before adding one, identify the actual rerender boundary and prefer structural fixes:65661. Split at the update boundary.672. Move transient state to its smallest owner.683. Use narrow Zustand selectors and avoid broad subscriptions.6970Do not memoize prop-free or trivially rendered components, or a component that normally receives new objects, arrays, functions, or JSX children. Do not use memoization to compensate for state held too high in the tree.7172Use memoization only when the subtree is demonstrably expensive or frequently repeated, its relevant inputs are stable during normal parent renders, and profiling or a concrete render-path analysis identifies the avoided work. State that reason in the implementation summary or PR.7374## Layout7576Use `Flexbox` and `Center` from `@lobehub/ui`. See `references/layout-kit.md` for full props and examples.7778- Use `gap` instead of `margin` for spacing between flex children79- Use `flex={1}` to fill available space80- Nest Flexbox for complex layouts; set `overflow: 'auto'` for scrollable regions8182## Related Skills8384- **`ux`**: loading visuals and user-facing interaction design. Do not use antd `Spin` / `<Spin />`.85- **`modal`**: imperative base-ui modal patterns.86- **`spa-routes`**: SPA navigation, route ownership, router configuration, and `.desktop` variants.87- **`compose-atoms`**: split a heavy domain feature into mountable capability atoms; each host imports only what it mounts.88- **`zustand`**: store structure and selector conventions.
lobehub