Splitter

A splitter allow create dynamic layouts split into vertically or horizontally arranged panes. Panes are separated by the splitter bars that allow dragging to resize or expand/collapse them.

Features

• Built with flexbox for flexible layout and SSR
• Support both dynamic horizontal and vertical panels
• Support multiple panels and splitters
• Support for collapsible panels
• Support for panel constraints like min and max sizes
• Programmatic control of panel sizes
• Implements the Window Splitter pattern for accessibility and keyboard controls

Installation

To use the splitter machine in your project, run the following command in your command line:

npm install @zag-js/splitter @zag-js/react
# or
yarn add @zag-js/splitter @zag-js/react

npm install @zag-js/splitter @zag-js/solid
# or
yarn add @zag-js/splitter @zag-js/solid

npm install @zag-js/splitter @zag-js/vue
# or
yarn add @zag-js/splitter @zag-js/vue

npm install @zag-js/splitter @zag-js/svelte
# or
yarn add @zag-js/splitter @zag-js/svelte

This command will install the framework agnostic splitter logic and the reactive utilities for your framework of choice.

Anatomy

To set up the slider correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Usage

First, import the splitter package into your project

import * as splitter from "@zag-js/splitter"

The splitter package exports two key functions:

• machine — The state machine logic for the splitter widget.
• connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll also need to provide a unique id to the useMachine hook. This is used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the splitter machine in your project 🔥

import * as splitter from "@zag-js/splitter"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function Splitter() {
  const service = useMachine(splitter.machine, {
    id: useId(),
    defaultSize: [
      { id: "a", size: 50 },
      { id: "b", size: 50 },
    ],
  })

  const api = slider.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getPanelProps({ id: "a" })}>
        <p>A</p>
      </div>
      <div {...api.getResizeTriggerProps({ id: "a:b" })} />
      <div {...api.getPanelProps({ id: "b" })}>
        <p>B</p>
      </div>
    </div>
  )
}

import * as splitter from "@zag-js/splitter"
import { normalizeProps, useMachine } from "@zag-js/solid"
import { createMemo, createUniqueId } from "solid-js"

export function Splitter() {
  const service = useMachine(splitter.machine, {
    id: createUniqueId(),
    defaultSize: [
      { id: "a", size: 50 },
      { id: "b", size: 50 },
    ],
  })

  const api = createMemo(() => splitter.connect(service, normalizeProps))

  return (
    <div {...api().getRootProps()}>
      <div {...api().getPanelProps({ id: "a" })}>
        <p>A</p>
      </div>
      <div {...api().getResizeTriggerProps({ id: "a:b" })} />
      <div {...api().getPanelProps({ id: "b" })}>
        <p>B</p>
      </div>
    </div>
  )
}

<script setup>
  import * as splitter from "@zag-js/splitter"
  import { normalizeProps, useMachine } from "@zag-js/vue"
  import { computed } from "vue"

  const service = useMachine(splitter.machine, {
    id: "1",
    defaultSize: [
      { id: "a", size: 50 },
      { id: "b", size: 50 },
    ],
  })

  const api = computed(() => splitter.connect(service, normalizeProps))
</script>

<template>
  <div v-bind="api.getRootProps()">
    <div v-bind="api.getPanelProps({ id: 'a' })">
      <p>A</p>
    </div>
    <div v-bind="api.getResizeTriggerProps({ id: 'a:b' })" />
    <div v-bind="api.getPanelProps({ id: 'b' })">
      <p>B</p>
    </div>
  </div>
</template>

<script lang="ts">
  import { normalizeProps, useMachine } from "@zag-js/svelte"
  import * as splitter from "@zag-js/splitter"

  const id = $props.id()
  const service = useMachine(splitter.machine, {
    id,
    defaultSize: [
        { id: "a", size: 50 },
        { id: "b", size: 50 },
      ],
  })
  const api = $derived(splitter.connect(service, normalizeProps))
</script>

<div {...api.getRootProps()}>
  <div {...api.getPanelProps({ id: "a" })}>
    <p>A</p>
  </div>
  <div {...api.getResizeTriggerProps({ id: "a:b" })}></div>
  <div {...api.getPanelProps({ id: "b" })}>
    <p>B</p>
  </div>
</div>

Listening for resize events

When the resize trigger of splitter changes, the onResizeStart and onResizeEnd callback is invoked.

const service = useMachine(splitter.machine, {
  // ...
  onResizeStart(detail) {
    console.log("change start", detail)
  },
  onResizeEnd(detail) {
    console.log("change end", detail)
  },
})

Changing the orientation

By default, the splitter is assumed to be horizontal. To change the orientation to vertical, set the orientation property in the machine's context to vertical.

const service = useMachine(splitter.machine, {
  // ...
  orientation: "vertical",
})

Specifying constraints

Use the panels property to specify constraints like minSize and maxSize for the splitter panels.

const service = useMachine(splitter.machine, {
  // ...
  panels: [
    { id: "a", minSize: 100, maxSize: 300 },
    { id: "b", minSize: 100, maxSize: 300 },
  ],
})

Setting the collapsed size

Use the collapsedSize and collapsible property to specify the collapsed size of the splitter panels.

const service = useMachine(splitter.machine, {
  // ...
  collapsedSize: 100,
  collapsible: true,
})

This allows the user to drag the splitter to collapse the panel to the collapsedSize.

Listening for collapse events

When the splitter panel is collapsed, the onCollapse callback is invoked. Alternatively, the onExpand callback is invoked when the panel is expanded.

const service = useMachine(splitter.machine, {
  // ...
  onCollapse(detail) {
    console.log("collapse", detail)
  },
  onExpand(detail) {
    console.log("expand", detail)
  },
})

Styling guide

Earlier, we mentioned that each accordion part has a data-part attribute added to them to select and style them in the DOM.

Resize trigger

When an splitter item is horizontal or vertical, a data-state attribute is set on the item and content elements.

[data-scope="splitter"][data-part="resize-trigger"] {
  /* styles for the item */
}

[data-scope="splitter"][data-part="resize-trigger"][data-orientation="horizontal"] {
  /* styles for the item is horizontal state */
}

[data-scope="splitter"][data-part="resize-trigger"][data-orientation="vertical"] {
  /* styles for the item is horizontal state */
}

[data-scope="splitter"][data-part="resize-trigger"][data-focus] {
  /* styles for the item is focus state */
}

[data-scope="splitter"][data-part="resize-trigger"]:active {
  /* styles for the item is active state */
}

[data-scope="splitter"][data-part="resize-trigger"][data-disabled] {
  /* styles for the item is disabled state */
}

Methods and Properties

• focusedbooleanWhether the splitter is focused.
• draggingbooleanWhether the splitter is being dragged.
• boundsPanelBoundsThe bounds of the currently dragged splitter handle.
• setToMinSize(id: PanelId) => voidFunction to set a panel to its minimum size.
• setToMaxSize(id: PanelId) => voidFunction to set a panel to its maximum size.
• setSize(id: PanelId, size: number) => voidFunction to set the size of a panel.
• getResizeTriggerState(props: ResizeTriggerProps) => ResizeTriggerStateReturns the state details for a resize trigger.