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/uiroot 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 |
|---|---|
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'; |
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 forModal,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 |
| Feedback | Alert, Drawer |
| Layout | Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow |
| Navigation | Burger, Menu, SideNav, Tabs |
Loading indicators
Do NOT use antd Spin / <Spin />. Use a project loader (NeuralNetworkLoading, DotsLoading, …) — see the ux skill ("Loading visuals") for the component table and when to use each.
State
When a feature component manages more than 3 pieces of state (useState/useReducer/derived state), extract the logic into a custom hook (e.g. useXxx). Keep the component focused on rendering — the hook holds state and handlers, so logic can be unit-tested without rendering the component.
Layout
Use Flexbox and Center from @lobehub/ui. See references/layout-kit.md for full props and examples.
- Use
gapinstead ofmarginfor spacing between flex children - Use
flex={1}to fill available space - Nest Flexbox for complex layouts; set
overflow: 'auto'for scrollable regions
Navigation
For SPA pages, use react-router-dom, NOT next/link.
// ❌ Wrong
import Link from 'next/link';
// ✅ Correct
import { Link, useNavigate } from 'react-router-dom';Access navigate from stores: useGlobalStore.getState().navigate?.('/settings');
Desktop File Sync Rule
Files with a .desktop.ts(x) variant must be edited in sync. Drift causes blank pages in Electron.
| Base file (web) | Desktop file (Electron) |
|---|---|
desktopRouter.config.tsx | desktopRouter.config.desktop.tsx |
componentMap.ts | componentMap.desktop.ts |
After editing any .ts/.tsx: glob for <filename>.desktop.{ts,tsx} in the same directory. If found, apply the equivalent sync-import change.
Routing Architecture
| Route Type | Use Case | Implementation |
|---|---|---|
| Next.js App Router | Auth pages | src/app/[variants]/(auth)/ |
| React Router DOM | Main SPA | desktopRouter.config.tsx + .desktop.tsx (pair) |
Router utilities:
import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
element: redirectElement('/settings/profile');
errorElement: <ErrorBoundary />;Common Mistakes
| Mistake | Fix |
|---|---|
Using next/link in SPA | Use react-router-dom Link |
| Using antd directly | Use @lobehub/ui/base-ui first, then @lobehub/ui |
antd Spin / <Spin /> for loading | Use NeuralNetworkLoading / project loaders (see the ux skill) |
import { Select } from '@lobehub/ui' | import { Select } from '@lobehub/ui/base-ui' |
import { Modal } from '@lobehub/ui' + <Modal open> declarative | createModal / confirmModal from @lobehub/ui/base-ui (see modal skill) |
import { DropdownMenu/Popover/Switch } from '@lobehub/ui' | Import same name from @lobehub/ui/base-ui instead |
createStyles for static styles | Use createStaticStyles + cssVar |
Editing only desktopRouter.config.tsx | Must edit both .tsx and .desktop.tsx |
Using margin for flex spacing | Use gap prop on Flexbox |
| Accessing zustand store without selector | Use selectors to access store data (see zustand skill) |
Text or icon-text actions built with Flexbox/Text + onClick | Use Button type={'text'} size={'small'} with icon when needed |
