Ladle

You can override global background settings by defining argTypes directly on a specific story. This allows you to provide a different set of color options or a different name for the control for that specific story context.

Note: Only one background control can be active at a time.

export const Story = () => <div>Hello</div>;
Story.argTypes = {
  background: {
    name: "Canvas background",
    control: { type: "background" },
    options: ["green", "yellow", "pink"],
    defaultValue: "pink",
  },
};

To use Emotion, install the required dependencies and configure the @vitejs/plugin-react-swc plugin in your vite.config.js to handle the JSX import source and SWC plugin.

pnpm add @emotion/react @swc/plugin-emotion @vitejs/plugin-react-swc

// vite.config.js
import react from "@vitejs/plugin-react-swc";

export default {
  plugins: [
    react({
      jsxImportSource: "@emotion/react",
      plugins: [["@swc/plugin-emotion", {}]],
    }),
  ],
};

The Test component is a stateful React component that makes requests to the uOwn backend and manages the state of the tree.

Before using the component, ensure the backend service is running by executing yarn add-service.

import { Test } from "test/react";

<Test
  onNodeChange={({ name, uuid }) => console.log(`Node selected ${name}`)}
  maxWidth="100%"
/>

To apply args and argTypes to every story in your project, define them in .ladle/components.tsx.

Control precedence (from highest to lowest):

1. Per-story controls
2. File-level controls
3. Global level controls

// .ladle/components.tsx
export const args = {
  label: "Hello world",
};

export const argTypes = {
  cities: {
    options: ["Prague", "NYC"],
    control: { type: "check" },
  },
};

You can override default naming and hierarchy using storyName for individual stories or the title property in the default export for grouping.

Rename a single story

Assign a string literal to the .storyName property of the exported story.

Customize hierarchy and levels

Use the title property in the default export (of type StoryDefault) to define the navigation path. Use / to create sublevels.

Note: All names (storyName, title, and meta) must be static string literals to support code-splitting.

import type { StoryDefault, Story } from "@ladle/react";

// Customizing hierarchy
export default {
  title: "Level / Sub level",
} satisfies StoryDefault;

export const Button: Story = () => <button>My Button</button>;

// Customizing individual story name
Button.storyName = "Renamed Button";

Ladle v3 introduces several breaking changes and improvements. Key updates include:

• Compiler: SWC is now the default, replacing Babel. This provides faster builds and startup. You can revert to Babel using @vite/plugin-react if necessary.
• Node.js Support: Official support for Node v18 and v20. Node v16 is deprecated.
• React Support: React 18+ is supported. React v17 is deprecated.
• New Features: MDX stories, mocked dates, and improved CSS-in-JS support (Emotion, Styled-components, Tailwind, etc.).
• API Changes: StoryDefault and Meta exported types are now interfaces to allow for easier extensions.

Ladle does not currently support third-party addons, but it includes several built-in addons accessible via button icons in the bottom left corner of the interface. These include:

• Accessibility (Axe)
• Background
• Controls (enabled only if args or argTypes are defined)
• Dark theme
• Links
• MSW (for API mocking)
• Preview mode
• Right-to-left
• Story source code
• Width

You can customize the header of the source addon by exporting a StorySourceHeader component from your .ladle/components.tsx file. The component receives a path prop representing the origin of the story, which you can use to provide custom information or hyperlinks (e.g., a GitHub link).

import type { SourceHeader } from "@ladle/react";

export const StorySourceHeader: SourceHeader = ({ path }) => {
  return (
    <b>
      Github link? <code className="ladle-code">{path}</code>
    </b>
  );
};