DOCSEARCHbyAlgolia
Submit Docs

svelte-tweakpane-ui

repository·main·Indexed 42 days ago

https://github.com/kitschpatrol/svelte-tweakpane-ui

A library of 34 reactive, type-safe Svelte components that wrap the Tweakpane UI library. It provides declarative ways to add knobs, dials, and monitors to creative tools, data visualizations, and simulations. Compatible with Svelte 4 and Svelte 5, the library includes Core, Control, Monitor, and Extra components, managing the lifecycle of Tweakpane objects automatically.

Tokens
12.8K
Snippets
36
Records
70
Agent score
53%

What's inside svelte-tweakpane-ui

  1. Overview of Svelte Tweakpane UI

    main

    Svelte Tweakpane UI is a library that wraps Tweakpane UI elements into idiomatic, reactive, and type-safe Svelte components. It bridges the gap between Tweakpane's imperative vanilla JS API and Svelte's declarative paradigm.

    Key Features

    • Compatibility: Works with Svelte 4, Svelte 5, SvelteKit, and Astro.
    • Reactive: Components dynamically update when props change.
    • Declarative: Handles lifecycle, DOM placement, binding, and event handling automatically.
    • Batteries Included: A single dependency provides access to all components, including several Tweakpane Plugins.
    • Flexible Binding: Uses Svelte's conventional bind:value approach, allowing components to act as either monitors (read-only) or controls (two-way binding) depending on how they are used.

  3. Understand Svelte Tweakpane UI naming conventions

    main

    The library uses predictable naming conventions for both TypeScript types and components to ensure discoverability and clarity.

    Type Names

    Types for component props (including the value prop) follow a structured pattern: {ComponentName}{PropName}{NarrowedType}

    For example, the <RotationEuler> component provides:

    • RotationEulerValueTuple: tuple type for the value prop
    • RotationEulerValueObject: object type for the value prop
    • RotationEulerValue: union type of object/tuple for the value prop
    • RotationEulerOrder: string literal union type for the order prop
    • RotationEulerUnit: string literal union type for the unit prop

    Component Names

    Most component names match the official Tweakpane documentation, with two key exceptions for Svelte-specific terminology:

    • Use <TabGroup> instead of the vanilla Tweakpane Tab.
    • Use <TabPage> instead of the vanilla Tweakpane Page.

    Because component names are terse (e.g., <Button>, <Image>), it is recommended to use namespace imports to avoid collisions with other UI libraries.

    <script lang="ts">
  import * as T from 'svelte-tweakpane-ui'
</script>

<T.Button />

  6. Component categories in Svelte Tweakpane UI

    main

    Components are exported from the svelte-tweakpane-ui package in a flat namespace and are organized into four functional groups:

    1. Core components: Concerned with structure and containment (e.g., Blade, Binding, Folder, Pane). They closely mirror vanilla Tweakpane building blocks.
    2. Control components: Abstractions for manipulating values (e.g., Slider, Point). These include controls from the Tweakpane Plugins ecosystem.
    3. Monitor components: Optimized for visualizing values rather than manipulating them.
    4. Extra components: Novelties and miscellaneous components.

  7. How theme scoping works

    main

    Themes in Svelte Tweakpane UI are scoped to ensure multiple themes can coexist on a single page. Scoping follows this hierarchy:

    1. Pane Scoping: Passing a theme prop to a <Pane> applies that theme to all its children. Note that a Pane's theme overrides any theme prop passed to its child components.
    2. Standalone Component Scoping: Passing a theme prop to a component that is not inside a <Pane> scopes the theme to that specific component.
    3. Global Scoping: Using ThemeUtils.setGlobalDefaultTheme() sets a theme for all components on the page. Individual panes or standalone components can still override this global default using their own theme prop.
    <script lang="ts">
  import { Button, ThemeUtils } from 'svelte-tweakpane-ui'
  // Sets the theme for all components on the page
  ThemeUtils.setGlobalDefaultTheme(ThemeUtils.presets.jetblack)
</script>

<Button label="I'm jet black, the custom global default" />
<Button label="I'm light" theme={ThemeUtils.presets.light} />

  8. Default theme behavior and rounding

    main

    By default, all components use ThemeUtils.presets.standard (a dark theme).

    Exception for Inline/Standalone components: To prevent aesthetic issues when stacking components, rounding is removed by default from the backgrounds of 'inline' components (those inside <Pane position="inline">) and 'standalone' components (those not inside a <Pane>). To restore rounding, explicitly pass a baseBorderRadius in the theme prop or set the theme to ThemeUtils.presets.standard.

  9. Understand dynamic props in components

    main

    To bridge the gap between Tweakpane's highly dynamic API and Svelte's static component API, several components feature dynamic props.

    These props are added or removed from a component at runtime based on the presence or type of other props. This is used to:

    • Avoid creating many similar components (e.g., for <Monitor>).
    • Prevent props from being silently ignored (e.g., the alpha prop on <Color> which only applies to number values).
    • Maintain clarity in components like <Pane>.

    Note: While autocompletion should adapt to these changes, you may see runtime console warnings if you change a dynamic prop on the fly in a way that is invalid for the current permutation of props.

  10. How Svelte Tweakpane UI components work compared to Vanilla Tweakpane

    main

    In vanilla Tweakpane, you must manually manage a PARAMS object, listen for update events, handle component lifecycles, and manually place controls in the DOM.

    In Svelte Tweakpane UI, these concerns are abstracted away. You simply use the component in your markup. The component handles its own lifecycle and DOM placement, and you use Svelte's bind: directive to connect the UI to your application state.

    <!-- Svelte Tweakpane UI Example -->
<Slider bind:value={myValue} min={0} max={100} />

  11. Understand Svelte Tweakpane UI API differences

    main

    The Svelte implementation differs from the vanilla Tweakpane API in several key ways:

    • No Manual Disposal: The library manages the lifecycle of underlying Tweakpane objects automatically.
    • No container or index props: Placement and order are managed by Svelte's DOM structure and component markup position.
    • Visibility via Svelte: Instead of a .hidden property, use Svelte logic (e.g., {#if condition}) to add or remove components from the DOM.
    • Props instead of Params: Configuration values that are passed as Params objects in vanilla Tweakpane are exposed as top-level props in Svelte components.
    • Renamed Components:
      • Vanilla Tab $\rightarrow$ <TabGroup>
      • Vanilla Page $\rightarrow$ <TabPage>

  12. How plugins work in Svelte Tweakpane UI

    main

    In Svelte Tweakpane UI, plugins are treated as regular Svelte components. Unlike the vanilla Tweakpane API, you do not need to manually npm install, import, and register plugins on a Pane object. Instead, the library manages plugin import and registration automatically the first time a plugin-based component is used.

    Key differences from vanilla Tweakpane:

    • Automatic Registration: No pane.registerPlugin(Plugin) call is required.
    • Explicit vs. Implicit: While vanilla Tweakpane often "picks" a control based on the value type (implicit), Svelte Tweakpane UI encourages explicit component selection (e.g., using <Slider> instead of an abstract <Binding>) to ensure type safety and clarity.