Pane

The root <Pane> component, used for organizing controls into a single group and controlling how and where the Tweakpane is displayed.

This component is a wrapper around Tweakpane's Pane class.

Important: Unlike the vanilla JS Tweakpane API, wrapping components in a <Pane> is not mandatory.

Pane-less components will be automatically nested in a <Pane position="inline"> component and displayed in the regular block flow of the page. <Pane> is only necessary when you want to explicitly group a number of components, or when you want convenient means to control how and where the Tweakpane is shown on the page. (See an important exception regarding Svelte Tweakpane UI in island frameworks like Astro.)

Multiple <Pane> components of different modes may be added to a single page. If the panes are in fixed or draggable mode, you might want to set the x or y properties to prevent overlap.

Note that <Pane> is a dynamic component, and availability of additional props will vary depending on the defined position value.

Position mode overview:

• <Pane position="draggable" ...>
  This is an extension of Tweakpane's core functionality, which reasonably considers pane dragging outside of the library's scope. See discussion in Tweakpane issues #88 and #301.
  
  By default, the pane's last position and width will be saved to the browser's local storage and re-applied across page reloads. (Set the storePositionLocally prop to false to prevent this.)
  
  If multiple <Pane position="draggable" ...> components are used on the same page with storePositionLocally set to true, then each must have a unique localStoreId prop set to avoid collisions.
  
  Double-clicking the width drag handle will expand or contract the pane between to its minWidth and maxWidth sizes.

• <Pane position="inline" ...>
  Provides an inline version of the pane component, allowing the Tweakpane window to appear in the normal flow of the document.
  
  All other Svelte Tweakpane UI components which are created without a containing <Pane> are nested implicitly inside a title-less <Pane position="inline"> component. As such, you do not necessarily need create <Pane position="inline"> components in most cases.
  
  This mode's behavior is similar to creating a Pane in the vanilla JS Tweakpane with its container property set to a specific element where you want the Pane to appear.

• <Pane position="fixed" ...>
  This mode uses the standard vanilla JS Tweakpane behavior of displaying in a fixed position over the top-right of the page.

---

Example

Demo

Code

PaneExample.svelte

<script lang="ts">
  import { Pane, type PanePosition, RadioGrid } from 'svelte-tweakpane-ui'

  const options: PanePosition[] = ['inline', 'fixed', 'draggable']
  let position: PanePosition = options[0]
</script>

<Pane {position} title="Pane" y={position === 'inline' ? undefined : 110}>
  <RadioGrid
    bind:value={position}
    columns={1}
    label="Pane Position Prop"
    values={options}
  />
</Pane>
{#if position === 'fixed'}
  <p>Pane is fixed at the top-right of the page.</p>
{:else if position === 'draggable'}
  <p>Pane is draggable at the top-right of the page.</p>
{/if}

<style>
  p {
    display: grid;
    place-content: center;
    width: 100%;
    height: 96px;
  }
</style>

---

Props

Dynamic Props

This component has dynamic props, which means the available props can change depending on the value or type of other props.

Props contingent on certain conditions are annotated below with a dynamic flag, and include explanations of the “conditions” affecting the prop’s availability. More Info →

position optional
Description	Pane mode, one of three options: 'draggable' (default) The pane is draggable and resizable, and may be placed anywhere over the page. 'inline' The pane appears inline with other content in the normal flow of the document. This is the default mode for components created outside of an explicit <Pane> component.* 'fixed' Standard Tweakpane behavior where the pane is shown in a fixed position over the page. Note that <Pane> is a dynamic component, and availability of additional props will vary depending on the defined position value.
Type	'draggable' | 'fixed' | 'inline'
Default	'draggable'

width bindableoptional
Description	Width of the pane, in pixels. Width of the pane, in pixels. If undefined, the pane will fill the width of its container. (This behavior is unique to position="inline".) This value is particularly important in combination with scale, since a scaled inline pane will grow indefinitely wider if an intrinsic width is not specified and a containing element is not provided. Width of the pane, in pixels. Setting explicitly via a passed prop will override saved user-specified width. Use this prop to set a starting width, or to monitor changes in the the pane's width when a user resizes it. Note that height is not exposed because it is determined dynamically by the pane's contents and state of its foldable elements. By default, the width value is saved to local storage for persistence across page loads.
Type	number
Default	256

title optional
Description	Text in the pane's title bar.
Type	string
Default	Tweakpane Unless position="inline", in which case the default is undefined and no title bar is shown.

userExpandable optional
Description	Allow users to interactively expand / contract the pane by clicking its title bar. Hides the collapse button from the title bar when false.
Type	boolean
Default	true

expanded bindableoptional
Description	Expand or collapse the pane into its title bar.
Type	boolean
Default	true

theme optional
Description	Custom color scheme. Applies to all child components, but note that setting a different theme on a child component's prop will not override the parent pane's theme. Note that <Pane position="inline' ...> squares off rounded corners by default to better integrate with surrounding content. Simply pass a custom or default theme like ThemeUtils.presets.standard if you want rounded corners on an inline pane. See also the setGlobalDefaultTheme() for a way to set a custom default theme for all panes on the page.
Type	Theme
Default	undefined Inherits default Tweakpane theme equivalent to ThemeUtils.presets.standard, or the theme set with setGlobalDefaultTheme().

scale optional
Description	Scales the pane's elements by a factor of scale to make it easier to see. Holds the width of the pane constant, so the pane will grow taller as it is scaled and will continue to respect position- and size-related props. If you need more breathing room, set the width property on the pane. Note that the scaling prop is only available on <Pane>, not on stand-alone (implicitly wrapped) inline elements. Negative values are ignored.
Type	number
Default	1

tpPane bindablereadonlyoptional
Description	The internal Tweakpane Pane object. This property is exposed for advanced use cases only. Direct manipulation of Tweakpane's internals can break Svelte Tweakpane UI abstractions. Note that the Pane type for this property comes from the core Tweakpane library. Creating an alias is suggested to avoid confusion with the Svelte Tweakpane UI Pane component: e.g. import { type Pane as TpPane } from 'tweakpane'
Type	Pane

collapseChildrenToFit optionaldynamic
Description	Automatically collapse open panels when the available window size is less than the height of the pane.
Type	boolean
Default	false
Conditions	Available when position="draggable".

localStoreId optionaldynamic
Description	Identifier to be used if multiple <Pane position="draggable"> components with storePositionLocally set to true are used on the same page.
Type	string
Default	'1'
Conditions	Available when position="draggable".

maxWidth optionaldynamic
Description	Maximum pane width in pixels.
Type	number
Default	600
Conditions	Available when position="draggable".

minWidth optionaldynamic
Description	Minimum pane width in pixels.
Type	number
Default	200
Conditions	Available when position="draggable".

padding optionaldynamic
Description	CSS padding property string to apply to the draggable pane container to prevent it from being dragged all the way to the edge of the window. Useful for keeping the pane away from of menu bars, etc.
Type	string
Default	'0'
Conditions	Available when position="draggable".

resizable optionaldynamic
Description	Allow the user to resize the width of the pane by dragging the right corner of the title bar.
Type	boolean
Default	true
Conditions	Available when position="draggable".

storePositionLocally optionaldynamic
Description	Store the pane's position and width when the user changes it interactively. Set the localStoreId prop if you have multiple draggable panes on the same page with storePositionLocally set to true.
Type	boolean
Default	true
Conditions	Available when position="draggable".

x bindableoptionaldynamic
Description	Horizontal position of the pane relative to the left edge of the window, in pixels. Not to be confused with the position prop which defines how, not where, the pane is positioned on the page. (So-named because of its similarity to CSS position property.) By default, this position is saved to local storage for persistence across page loads.
Type	number
Default	0
Conditions	Available when position="draggable" or position="fixed".

y bindableoptionaldynamic
Description	Vertical position of the pane relative to the top of the window, in pixels. Not to be confused with the position prop which defines how, not where, the pane is positioned on the page. (So-named because of its similarity to CSS position property.) By default, this position is saved to local storage for persistence across page loads.
Type	number
Default	0
Conditions	Available when position="draggable" or position="fixed".

---

Slots

default
Description	Any Tweakpane component, except another <Pane>.
Type	{}