React

React Component Writing Guide

Styling

Component Priority

1. `src/components` — project-specific reusable components 2. `@lobehub/ui/base-ui` — headless primitives. If the component lives here, use it. Do NOT import the same-named root export. 3. `@lobehub/ui` — higher-level / antd-wrapping components (only when no base-ui equivalent) 4. antd — only when neither base-ui nor @lobehub/ui root provides it 5. 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

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

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 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

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.

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

Router utilities:

import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
element: redirectElement('/settings/profile');
errorElement: <ErrorBoundary />;

Common Mistakes

Flexbox Layout Components Guide

@lobehub/ui provides Flexbox and Center components for creating flexible layouts.

Flexbox Component

Flexbox is the most commonly used layout component, similar to CSS display: flex.

Basic Usage

import { Flexbox } from '@lobehub/ui';

// Default vertical layout
<Flexbox>
  <div>Child 1</div>
  <div>Child 2</div>
</Flexbox>

// Horizontal layout
<Flexbox horizontal>
  <div>Left</div>
  <div>Right</div>
</Flexbox>

Common Props

• horizontal: Boolean, set horizontal direction layout
• flex: Number or string, controls flex property
• gap: Number, spacing between children
• align: Alignment like 'center', 'flex-start', etc.
• justify: Main axis alignment like 'space-between', 'center', etc.
• padding: Padding value
• paddingInline: Horizontal padding
• paddingBlock: Vertical padding
• width/height: Set dimensions, typically '100%' or specific pixels
• style: Custom style object

Layout Example

// Classic three-column layout
<Flexbox horizontal height={'100%'} width={'100%'}>
  {/* Left sidebar */}
  <Flexbox
    width={260}
    style={{
      borderRight: `1px solid ${theme.colorBorderSecondary}`,
      height: '100%',
      overflowY: 'auto',
    }}
  >
    <SidebarContent />
  </Flexbox>

  {/* Center content */}
  <Flexbox flex={1} style={{ height: '100%' }}>
    <Flexbox flex={1} padding={24} style={{ overflowY: 'auto' }}>
      <MainContent />
    </Flexbox>

    {/* Footer */}
    <Flexbox
      style={{
        borderTop: `1px solid ${theme.colorBorderSecondary}`,
        padding: '16px 24px',
      }}
    >
      <Footer />
    </Flexbox>
  </Flexbox>
</Flexbox>

Center Component

Center wraps Flexbox with horizontal and vertical centering.

import { Center } from '@lobehub/ui';

<Center width={'100%'} height={'100%'}>
  <Content />
</Center>

// Icon centered
<Center className={styles.icon} flex={'none'} height={40} width={40}>
  <Icon icon={icon} size={24} />
</Center>

Best Practices

• Use flex={1} to fill available space
• Use gap instead of margin for spacing
• Nest Flexbox for complex layouts
• Set overflow: 'auto' for scrollable content
• Use horizontal for horizontal layout (default is vertical)
• Combine with useTheme hook for theme-responsive layouts