Splitter

A component that divides your interface into resizable sections

Anatomy

To set up the splitter 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.

Examples

Learn how to use the Splitter component in your project. Let's take a look at the most basic example:

import { Splitter } from '@ark-ui/react/splitter'

export const Basic = () => (
  <Splitter.Root
    defaultSize={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
  >
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
)

import { Splitter } from '@ark-ui/solid/splitter'

export const Basic = () => (
  <Splitter.Root
    size={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
  >
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
)

<script setup lang="ts">
import { Splitter } from '@ark-ui/vue/splitter'
import { ref } from 'vue'

const size = ref([
  { id: 'a', size: 50 },
  { id: 'b', size: 50 },
])
</script>

<template>
  <Splitter.Root :size="size">
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
</template>

Using Render Props

The Splitter component allows you to pass a function as a child to gain direct access to its API. This provides more control and allows you to modify the size of the panels programmatically:

import { Splitter } from '@ark-ui/react/splitter'

export const RenderProp = () => (
  <Splitter.Root
    defaultSize={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
  >
    <Splitter.Context>
      {(splitter) => (
        <>
          <Splitter.Panel id="a">
            <button type="button" onClick={() => splitter.setSize('a', 10)}>
              Set to 10%
            </button>
          </Splitter.Panel>
          <Splitter.ResizeTrigger id="a:b" />
          <Splitter.Panel id="b">
            <button type="button" onClick={() => splitter.setSize('b', 10)}>
              Set to 10%
            </button>
          </Splitter.Panel>
        </>
      )}
    </Splitter.Context>
  </Splitter.Root>
)

import { Splitter } from '@ark-ui/solid/splitter'

export const RenderProp = () => (
  <Splitter.Root
    size={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
  >
    <Splitter.Context>
      {(api) => (
        <>
          <Splitter.Panel id="a">
            <button type="button" onClick={() => api().setSize('a', 10)}>
              Set to 10%
            </button>
          </Splitter.Panel>
          <Splitter.ResizeTrigger id="a:b" />
          <Splitter.Panel id="b">
            <button type="button" onClick={() => api().setSize('b', 10)}>
              Set to 10%
            </button>
          </Splitter.Panel>
        </>
      )}
    </Splitter.Context>
  </Splitter.Root>
)

<script setup lang="ts">
import { Splitter } from '@ark-ui/vue/splitter'
import { ref } from 'vue'

const size = ref([
  { id: 'a', size: 50 },
  { id: 'b', size: 50 },
])
</script>

<template>
  <Splitter.Root :size="size">
    <Splitter.Context v-slot="splitter">
      <Splitter.Panel id="a">
        <button @click="splitter.setSize('a', 10)">Set A to 10%</button>
      </Splitter.Panel>
      <Splitter.ResizeTrigger id="a:b" />
      <Splitter.Panel id="b">
        <button @click="splitter.setSize('b', 10)">Set B to 10%</button>
      </Splitter.Panel>
    </Splitter.Context>
  </Splitter.Root>
</template>

Handling Events

Splitter also provides onSizeChangeStart and onSizeChangeEnd events which can be useful to perform some actions during the start and end of the resizing process:

import { Splitter } from '@ark-ui/react/splitter'

export const Events = () => (
  <Splitter.Root
    defaultSize={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
    onSizeChange={(details) => console.log('onSizeChange', details)}
    onSizeChangeEnd={(details) => console.log('onSizeChangeEnd', details)}
  >
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
)

import { Splitter } from '@ark-ui/solid/splitter'

export const Events = () => (
  <Splitter.Root
    size={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
    onSizeChange={(details) => console.log('onSizeChange', details)}
    onSizeChangeEnd={(details) => console.log('onSizeChangeEnd', details)}
  >
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
)

<script setup lang="ts">
import { Splitter } from '@ark-ui/vue/splitter'
import { ref } from 'vue'

const size = ref([
  { id: 'a', size: 50 },
  { id: 'b', size: 50 },
])
</script>

<template>
  <Splitter.Root
    :size="size"
    @size-change="(details) => console.log('onSizeChange', details)"
    @size-change-end="(details) => console.log('onSizeChangeEnd', details)"
  >
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
</template>

Vertical Splitter

By default, the Splitter component is horizontal. If you need a vertical splitter, use the orientation prop:

import { Splitter } from '@ark-ui/react/splitter'

export const Vertical = () => (
  <Splitter.Root
    orientation="vertical"
    defaultSize={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
  >
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
)

import { Splitter } from '@ark-ui/solid/splitter'

export const Vertical = () => (
  <Splitter.Root
    orientation="vertical"
    size={[
      { id: 'a', size: 50 },
      { id: 'b', size: 50 },
    ]}
  >
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
)

<script setup lang="ts">
import { Splitter } from '@ark-ui/vue/splitter'
import { ref } from 'vue'

const size = ref([
  { id: 'a', size: 50 },
  { id: 'b', size: 50 },
])
</script>

<template>
  <Splitter.Root :size="size" orientation="vertical">
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.Root>
</template>

Using the Root Provider

The RootProvider component provides a context for the splitter. It accepts the value of the useSplitter hook. You can leverage it to access the component state and methods from outside the splitter.

import { Splitter, useSplitter } from '@ark-ui/react/splitter'

export const RootProvider = () => {
  const splitter = useSplitter({ defaultSize: [{ id: 'a', size: 50 }] })

  return (
    <>
      <button onClick={() => splitter.setToMaxSize('a')}>Maximize a</button>

      <Splitter.RootProvider value={splitter}>
        <Splitter.Panel id="a">A</Splitter.Panel>
        <Splitter.ResizeTrigger id="a:b" />
        <Splitter.Panel id="b">B</Splitter.Panel>
      </Splitter.RootProvider>
    </>
  )
}

import { Splitter, useSplitter } from '@ark-ui/solid/splitter'

export const RootProvider = () => {
  const splitter = useSplitter({ size: [{ id: 'a', size: 50 }] })

  return (
    <>
      <button onClick={() => splitter().setToMaxSize('a')}>Maximize a</button>

      <Splitter.RootProvider value={splitter}>
        <Splitter.Panel id="a">A</Splitter.Panel>
        <Splitter.ResizeTrigger id="a:b" />
        <Splitter.Panel id="b">B</Splitter.Panel>
      </Splitter.RootProvider>
    </>
  )
}

<script setup lang="ts">
import { Splitter, useSplitter } from '@ark-ui/vue/splitter'
import { ref } from 'vue'

const size = ref([
  { id: 'a', size: 50 },
  { id: 'b', size: 50 },
])

const splitter = useSplitter({ size: size.value })
</script>

<template>
  <button @click="splitter.setToMaxSize('a')">Maximize a</button>

  <Splitter.RootProvider :value="splitter">
    <Splitter.Panel id="a">A</Splitter.Panel>
    <Splitter.ResizeTrigger id="a:b" />
    <Splitter.Panel id="b">B</Splitter.Panel>
  </Splitter.RootProvider>
</template>

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Root

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`defaultSize`		`PanelSizeData[]` The initial size of the panels when it is first rendered. Use this when you do not need to control the state of the carousel.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string resizeTrigger(id: string): string label(id: string): string panel(id: string \| number): string }>` The ids of the elements in the splitter. Useful for composition.
`orientation`		`'horizontal' \| 'vertical'` The orientation of the splitter. Can be `horizontal` or `vertical`
`size`		`PanelSizeData[]` The size data of the panels

Emit	Event
`sizeChange`	`[details: SizeChangeDetails]` Function called when the splitter is resized.
`sizeChangeEnd`	`[details: SizeChangeDetails]` Function called when the splitter resize ends.

Data Attribute	Value
`[data-scope]`	splitter
`[data-part]`	root
`[data-orientation]`	The orientation of the splitter

Panel

Prop	Default	Type
`id`		`PanelId`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`snapSize`		`number`

Data Attribute	Value
`[data-scope]`	splitter
`[data-part]`	panel
`[data-orientation]`	The orientation of the panel

ResizeTrigger

Prop	Default	Type
`id`		type ONLY_FOR_FORMAT = \| `${string}:${string}` \| `${string}:${number}` \| `${number}:${string}` \| `${number}:${number}`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`disabled`		`boolean`
`step`		`number`

Data Attribute	Value
`[data-scope]`	splitter
`[data-part]`	resize-trigger
`[data-orientation]`	The orientation of the resizetrigger
`[data-focus]`	Present when focused
`[data-disabled]`	Present when disabled

RootProvider

Prop	Default	Type
`value`		`MachineApi<PropTypes>`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Accessibility

Complies with the Window Splitter WAI-ARIA design pattern.