swizzle - Refine

The swizzle command allows you to export components or functions from Refine packages to customize them in your project. This gives you full control over the UI and behavior without losing the ability to update Refine packages.

Usage

refine swizzle

How It Works

The swizzle command:

Scans your project for installed Refine packages with swizzle configuration
Presents an interactive list of packages to choose from
Shows available components/functions from the selected package
Exports the selected component to your project’s source directory
Automatically installs any required dependencies
Preserves code formatting and imports

What Can Be Swizzled

You can swizzle components and functions from various Refine packages:

UI Framework Packages - Ant Design, Material UI, Mantine, Chakra UI components
Core Packages - Hooks, utilities, and helper functions
Data Providers - Provider implementations
Auth Providers - Authentication logic

Examples

Interactive Mode

Run the swizzle command to start the interactive process:

refine swizzle

Output

┌─────────────────────────────────────────────────────────────┐
│        Found 5 installed Refine packages with               │
│              swizzle configuration.                         │
└─────────────────────────────────────────────────────────────┘

? Which package do you want to swizzle?
  ❯ Ant Design
    Material UI
    Mantine
    @refinedev/core
    @refinedev/react-router

Swizzle an Ant Design Component

Swizzle a table component from Ant Design:

refine swizzle

Select Ant Design from the package list
Select the component you want to customize (e.g., <List>, <Edit>, <Show>)
The component will be exported to your src/components directory

Output

✓ Component exported successfully!

📁 Created files:
  src/components/list/index.tsx

💡 You can now customize this component to fit your needs.
   Import it in your pages to use the customized version.

Swizzle with Auto Dependencies

When you swizzle a component that requires additional packages, they’re automatically installed:

refine swizzle

Select a component that needs dependencies:

Output

✓ Component exported successfully!

📦 Installing required packages:
  @ant-design/icons
  dayjs

✓ Dependencies installed

Exported File Structure

When you swizzle a component, it’s exported to your source directory with the following structure:

src/
├── components/
│   └── list/
│       └── index.tsx    # Swizzled component

The exported file includes:

Complete component source code
All necessary imports
Type definitions
Default export for easy importing

Using Swizzled Components

After swizzling a component, import and use it in your application:

src/pages/products/list.tsx

import { List } from "@components/list";

export const ProductList = () => {
  return (
    <List>
      {/* Your customizations here */}
    </List>
  );
};

Customization Examples

Custom List Component

After swizzling the List component, customize the header:

src/components/list/index.tsx

import { Card } from "antd";

export const List: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return (
    <Card
      title="My Custom List Header"
      extra={<button>Custom Action</button>}
    >
      {children}
    </Card>
  );
};

Custom Hook Implementation

Swizzle and modify a core hook:

src/hooks/useCustomTable.ts

import { useTable } from "@refinedev/core";

export const useCustomTable = () => {
  const table = useTable({
    // Add your custom default configuration
    pagination: {
      pageSize: 20,
    },
  });

  return table;
};

File Transformations

The swizzle command applies several transformations:

Import Reordering - Organizes imports for better readability
Code Formatting - Applies Prettier formatting automatically
Block Parsing - Removes internal swizzle markers
Path Resolution - Updates relative import paths

Component Groups

Components are organized by groups for easier navigation:

Ant Design

Layout - Sider, Header, Footer, Title
CRUD - List, Create, Edit, Show
Fields - Text, Number, Date, Boolean, Email, URL
Buttons - Create, Edit, Delete, Show, Clone, Refresh

Material UI

Layout - Sider, Header, Footer, Title
CRUD - List, Create, Edit, Show
Fields - Text, Number, Date, Boolean, Email, URL
Buttons - Create, Edit, Delete, Show, Clone, Refresh

Core

Hooks - Data hooks, auth hooks, router hooks
Utilities - Helper functions and utilities

Best Practices

1. Swizzle Only What You Need

Don’t swizzle components unnecessarily. Only export components you need to customize:

# Only swizzle when you need customization
refine swizzle

2. Maintain Compatibility

When customizing swizzled components, maintain the same props interface:

// ✓ Good - maintains the original interface
export const List: React.FC<ListProps> = (props) => {
  return <CustomList {...props} />;
};

// ✗ Bad - breaking the interface
export const List = (newProps) => {
  return <CustomList />;
};

3. Document Your Changes

Add comments explaining your customizations:

// Swizzled from @refinedev/antd v5.36.0
// Customization: Added company logo to header
export const Header = () => {
  return (
    <div>
      <img src="/logo.png" alt="Company" />
      {/* Original header content */}
    </div>
  );
};

4. Version Control

Commit swizzled components to version control:

git add src/components/
git commit -m "Swizzle List component for custom styling"

5. Keep Track of Updates

When updating Refine packages, review changes to swizzled components:

# Before updating
refine swizzle  # Re-swizzle to a different location
# Compare changes manually

Package-Specific Examples

Ant Design Package

Swizzle the Edit component:

refine swizzle
# Select: Ant Design > Edit

Customize the Edit component:

src/components/edit/index.tsx

import { Edit as AntdEdit } from "antd";

export const Edit = (props) => {
  return (
    <AntdEdit
      {...props}
      saveButtonProps={{
        ...props.saveButtonProps,
        size: "large",
      }}
    />
  );
};

Material UI Package

Swizzle the DataGrid component:

refine swizzle
# Select: Material UI > DataGrid

Core Package

Swizzle a custom hook:

refine swizzle
# Select: @refinedev/core > useTable

Troubleshooting

No Packages Found

If you see “No Refine packages found with swizzle configuration”:

# Install a UI package first
npm install @refinedev/antd

Component Already Exists

If the target file already exists:

Output

✗ Component already exists at:
  src/components/list/index.tsx

Delete or rename the existing file to continue.

Solution:

# Rename or backup the existing file
mv src/components/list/index.tsx src/components/list/index.backup.tsx

# Run swizzle again
refine swizzle

Source Path Not Found

If the source component can’t be found:

Ensure the package is properly installed
Update to the latest version of the package
Check package integrity:

rm -rf node_modules package-lock.json
npm install

Import Errors After Swizzling

If you get import errors after swizzling:

Check your TypeScript configuration
Verify path aliases in tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@components/*": ["./src/components/*"]
    }
  }
}

Restart your development server:

refine dev

Missing Dependencies

If required packages aren’t installed automatically:

# Check the error message for required packages
# Install them manually
npm install @ant-design/icons dayjs

Advanced Usage

Custom Component Paths

By default, components are exported to src/components/. The path is determined by your project structure.

Re-swizzling Components

To update a swizzled component:

Delete or rename the existing file
Run refine swizzle again
Manually merge your customizations

Swizzle Multiple Components

Swizzle components one at a time, committing after each:

refine swizzle  # Swizzle List
git commit -m "Swizzle List component"

refine swizzle  # Swizzle Edit
git commit -m "Swizzle Edit component"

Migration Considerations

When updating Refine packages:

Check Breaking Changes - Review changelog for swizzled components
Test Thoroughly - Swizzled components may need updates
Re-swizzle if Needed - Compare with new versions and update accordingly

Getting Started

Commands

​Usage

​How It Works

​What Can Be Swizzled

​Examples

​Interactive Mode

​Swizzle an Ant Design Component

​Swizzle with Auto Dependencies

​Exported File Structure

​Using Swizzled Components

​Customization Examples

​Custom List Component

​Custom Hook Implementation

​File Transformations

​Component Groups

​Ant Design

​Material UI

​Core

​Best Practices

​1. Swizzle Only What You Need

​2. Maintain Compatibility

​3. Document Your Changes

​4. Version Control

​5. Keep Track of Updates

​Package-Specific Examples

​Ant Design Package

​Material UI Package

​Core Package

​Troubleshooting

​No Packages Found

​Component Already Exists

​Source Path Not Found

​Import Errors After Swizzling

​Missing Dependencies

​Advanced Usage

​Custom Component Paths

​Re-swizzling Components

​Swizzle Multiple Components

​Migration Considerations

​Next Steps

Build docs developers (and LLMs) love

Usage

How It Works

What Can Be Swizzled

Examples

Interactive Mode

Swizzle an Ant Design Component

Swizzle with Auto Dependencies

Exported File Structure

Using Swizzled Components

Customization Examples

Custom List Component

Custom Hook Implementation

File Transformations

Component Groups

Ant Design

Material UI

Core

Best Practices

1. Swizzle Only What You Need

2. Maintain Compatibility

3. Document Your Changes

4. Version Control

5. Keep Track of Updates

Package-Specific Examples

Ant Design Package

Material UI Package

Core Package

Troubleshooting

No Packages Found

Component Already Exists

Source Path Not Found

Import Errors After Swizzling

Missing Dependencies

Advanced Usage

Custom Component Paths

Re-swizzling Components

Swizzle Multiple Components

Migration Considerations

Next Steps