# Splitter

A draggable separator that coordinates the size of two panes.

## Usage

Use standalone. The consumer supplies layout CSS that matches `orientation`; Splitter ships no layout CSS and only emits the first-pane size, e.g. `display:flex` with `flex-basis: var(--svs-splitter)`.
```svelte
<Splitter {left} {right} />
```

## Anatomy

The `class` attribute values represent part names. Other attributes represent their corresponding props. The consumer supplies layout CSS that matches `orientation`; Splitter ships no layout CSS and only emits the first-pane size.

```svelte
<div class="whole" {...rest} style data-orientation data-dragging>
  <div class="left" id>{left}</div>
  <div class="main" role="separator" tabindex="0" aria-controls aria-orientation aria-valuenow aria-valuemin aria-valuemax aria-label>
    {children}
  </div>
  <div class="right">{right}</div>
</div>
```

`orientation` drives the drag axis and arrow-key model: horizontal uses `clientX` / Left / Right, vertical uses `clientY` / Up / Down. The root emits a renameable first-pane size custom property (`--svs-splitter` by default, or `cssvar.position`) and exposes `data-orientation`; `data-dragging` is present only during an active pointer drag. Arrow keys move by `step`, Home moves to `min`, End moves to `max`, and keyboard movement clamps without snap. Pointer drag clamps and snaps to the nearest `snap` target within 3 percentage points. `aria-orientation` is perpendicular to layout orientation because it describes the separator bar itself: a left|right split has a vertical separator.

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `left*` | `Snippet` | - | Left pane content; receives variant |
| `right*` | `Snippet` | - | Right pane content; receives variant |
| `children` | `Snippet` | - | Splitter handle content; receives value and variant |
| `orientation` | `<enum>` | `"horizontal"` | Drag axis and keyboard arrow model |
| `value` | `number` | `50` | Bindable first-pane percentage |
| `min` | `number` | `0` | Minimum first-pane percentage |
| `max` | `number` | `100` | Maximum first-pane percentage |
| `step` | `number` | `1` | Keyboard step |
| `snap` | `number[]` | - | Pointer-drag snap targets |
| `label` | `string` | - | Accessible label for the separator |
| `cssvar` | `Record` | - | Renames the emitted first-pane size custom property |
| `attach` | `Attachment` | - | Svelte attachment on the root div |
| `element` | `HTMLDivElement` | - | Bindable root div element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Variant |
`*` required. Other `HTMLAttributes` are passed to the root `<div>` via rest props; `class` is merged onto the root.

Consumer layout CSS is required. For a horizontal split, use `display:flex` on `whole` and consume `--svs-splitter` with `flex-basis: var(--svs-splitter)` on the first pane.

`aria-orientation` is perpendicular to `orientation` because it describes the separator bar itself.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching.

### Default Class Name

`svs-splitter`

## Behavior

`orientation` drives the drag axis and arrow-key model: horizontal uses `clientX` / Left / Right, vertical uses `clientY` / Up / Down. The root emits a renameable first-pane size custom property (`--svs-splitter` by default, or `cssvar.position`) and exposes `data-orientation`; `data-dragging` is present only during an active pointer drag. Arrow keys move by `step`, Home moves to `min`, End moves to `max`, and keyboard movement clamps without snap. Pointer drag clamps and snaps to the nearest `snap` target within 3 percentage points. `aria-orientation` is perpendicular to layout orientation because it describes the separator bar itself: a left|right split has a vertical separator.

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `ArrowLeft` | When `orientation` is `"horizontal"`, decreases the first pane size by `step` |
| `ArrowRight` | When `orientation` is `"horizontal"`, increases the first pane size by `step` |
| `ArrowUp` | When `orientation` is `"vertical"`, decreases the first pane size by `step` |
| `ArrowDown` | When `orientation` is `"vertical"`, increases the first pane size by `step` |
| `Home` | Moves the separator to `min` |
| `End` | Moves the separator to `max` |
Keyboard movement clamps to `min` / `max` and does not apply `snap` targets.

### ARIA Roles and Attributes

The component applies these automatically:

- Separator (`main`): `role="separator"`, `tabindex="0"`, `aria-controls` (the first pane), `aria-orientation`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-label` from `label`.

Provide an accessible name for the separator yourself because there is no built-in visible label. Pass the `label` prop. The managed separator role and value attributes are component-owned and omitted from `SplitterProps`.

## Exports

### Types

```ts
type SplitterCssVar = "position";
interface SplitterProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "role" | "style"> {
  left: Snippet<[string]>; // Snippet<[variant]>
  right: Snippet<[string]>; // Snippet<[variant]>
  children?: Snippet<[number, string]>; // Snippet<[value,variant]>
  orientation?: "horizontal" | "vertical"; // ("horizontal")
  value?: number; // bindable (50)
  min?: number; // (0)
  max?: number; // (100)
  step?: number; // (1)
  snap?: number[]; // pointer-drag snap targets, within 3 percentage points
  label?: string;
  cssvar?: Partial<Record<SplitterCssVar, string>>;
  attach?: Attachment<HTMLDivElement>;
  element?: HTMLDivElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // class & other HTMLAttributes are passed to the root <div> via ...rest (class is merged onto root)
  // role and style are component-owned
}
type SplitterReqdProps = "left" | "right";
type SplitterBindProps = "value" | "element";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=SplitterBasic.svelte
<script lang="ts">
  import { Splitter } from "svseeds";

  const styling = {
    whole: "flex h-40 w-full min-w-60 max-w-xl overflow-hidden rounded-md border bg-white dark:bg-black",
    left: "basis-[var(--svs-splitter)] min-w-0 bg-gray-400/30 p-4 overflow-hidden",
    main: "w-2 cursor-col-resize bg-gray-400 outline-hidden focus:bg-teal-500",
    right: "min-w-0 flex-1 p-4 overflow-hidden",
  };
  const myProps = {
    value: 38,
    min: 20,
    max: 80,
    label: "Resize preview panels",
    styling,
  };
</script>

<Splitter {...myProps}>
  {#snippet left()}
    <div class="text-sm font-medium">Navigation</div>
    <p class="mt-2 text-sm">Drag the divider to resize this pane.</p>
  {/snippet}

  {#snippet right()}
    <div class="text-sm font-medium">Content</div>
    <p class="mt-2 text-sm">The first pane consumes var(--svs-splitter).</p>
  {/snippet}
</Splitter>
```
### With Interactive Variant

**Code**

```svelte src=SplitterPract.svelte
<script lang="ts">
  import { Splitter } from "svseeds";

  let { variant = $bindable() } = $props();
  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const styling1 = {
    whole: {
      base: "flex h-80 w-0.8 max-w-xl overflow-hidden rounded-md border bg-white dark:bg-black",
      ...variantStyle,
    },
    left: "basis-[var(--svs-splitter)] min-w-0 bg-gray-400/30 p-4",
    main: "w-2 cursor-col-resize bg-gray-400 outline-hidden focus:bg-teal-500",
    right: "min-w-0 flex-1",
  };
  const myProps1 = {
    value: 40,
    min: 20,
    max: 80,
    label: "Resize workspace panels",
    styling: styling1,
  };
  const styling2 = {
    whole: "flex flex-col size-full overflow-hidden bg-white dark:bg-black",
    left: "basis-[var(--svs-splitter)] min-w-0 bg-gray-400/30 p-4 overflow-hidden",
    main: "h-2 cursor-row-resize bg-gray-400 outline-hidden focus:bg-teal-500",
    right: "min-w-0 flex-1 p-4 overflow-hidden",
  };
  const myProps2 = {
    value: 45,
    min: 20,
    max: 80,
    orientation: "vertical" as const,
    snap: [30, 50, 70],
    label: "Resize workspace panels",
    styling: styling2,
  };
</script>

<Splitter {variant} {...myProps1}>
  {#snippet left()}
    <div class="text-sm font-medium">Navigater</div>
    <p class="mt-2 text-sm">Drag the divider to resize this pane.</p>
  {/snippet}
  {#snippet right()}
    <Splitter {variant} {...myProps2}>
      {#snippet left()}
        <div class="text-sm font-medium">Inspector</div>
        <p class="mt-2 text-sm">Snap targets are set at 30, 50, and 70.</p>
      {/snippet}

      {#snippet right()}
        <div class="text-sm font-medium">Preview</div>
        <p class="mt-2 text-sm">Arrow keys move the separator by step.</p>
      {/snippet}
    </Splitter>
  {/snippet}
</Splitter>
```