Skip to content
Svelte Tweakpane UI
Core Components

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

🔗

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.

Typenumber
Default256

title

🔗
optional
Description

Text in the pane's title bar.

Typestring
DefaultTweakpane
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.

Typeboolean
Defaulttrue

expanded

🔗
bindableoptional
Description

Expand or collapse the pane into its title bar.

Typeboolean
Defaulttrue

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.

TypeTheme
Defaultundefined
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.

Typenumber
Default1

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'

TypePane

collapseChildrenToFit

🔗
optionaldynamic
Description

Automatically collapse open panels when the available window size is less than the height of the pane.

Typeboolean
Defaultfalse
ConditionsAvailable 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.

Typestring
Default'1'
ConditionsAvailable when position="draggable".

maxWidth

🔗
optionaldynamic
Description

Maximum pane width in pixels.

Typenumber
Default600
ConditionsAvailable when position="draggable".

minWidth

🔗
optionaldynamic
Description

Minimum pane width in pixels.

Typenumber
Default200
ConditionsAvailable 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.

Typestring
Default'0'
ConditionsAvailable 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.

Typeboolean
Defaulttrue
ConditionsAvailable 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.

Typeboolean
Defaulttrue
ConditionsAvailable 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.

Typenumber
Default0
ConditionsAvailable 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.

Typenumber
Default0
ConditionsAvailable when position="draggable" or position="fixed".

Slots

🔗

default

🔗
Description

Any Tweakpane component, except another <Pane>.

Type{}