Image

An image input control.

Important: This component has some rough edges, and should be considered experimental.

Integrates the tweakpane-image-plugin, incorporating work by Florian Morel, Matheus Dias, Palash Bansal, and others.

Use the <File> control instead if you're working with other file types, or don't wish to display a thumbnail preview of an uploaded image.

There is currently a known bug where change events' origin values are sometimes incorrect. (This issue is limited to this component.)

Usage outside of a <Pane> component will implicitly wrap the image control in <Pane position="inline">.

Note that Svelte Tweakpane UI embeds a functionally identical fork of the plugin with build optimizations. The fork also changes the package name to @kitschpatrol/tweakpane-plugin-image for consistency with other plugins.

---

Example

Demo

Tap “No Image” above to load an image from disk.

Or tap "Load Placeholder" to show a random image from the web.

Code

ImageExample.svelte

<script lang="ts">
  import { Button, Image, type ImageValue } from 'svelte-tweakpane-ui'

  let source: ImageValue
</script>

<Image bind:value={source} fit="contain" label="Image" />
<Button
  on:click={() => {
    const randomIndex = Math.floor(Math.random() * 1000)
    source = `https://static.photos/textures/640x360/${randomIndex}`
  }}
  label="Random Placeholder"
  title="Load Placeholder"
/>

<div class="demo">
  {#if source === undefined}
    <p>Tap “No Image” above to load an image from disk.</p>
    <p>Or tap "Load Placeholder" to show a random image from the web.</p>
  {:else if typeof source === 'string'}
    <img alt="" src={source} />
  {/if}
</div>

<style>
  div.demo {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    aspect-ratio: 1;
    width: 100%;
    background: linear-gradient(magenta, orange);
  }

  div.demo > img {
    max-width: 80%;
    max-height: 80%;
  }

  div.demo > p {
    max-width: 50%;
    color: white;
    text-align: center;
  }
</style>

---

Props

options optional
Description	Tweakpane's internal options object. See BindingParams. Valid types are contingent on the type of the value key points to in object. This is intended internal use, when implementing convenience components wrapping Binding's functionality. Options of interest are instead exposed as top-level props in Svelte Tweakpane UI.
Type	BaseInputParams
Default	undefined

disabled optional
Description	Prevent interactivity and gray out the control.
Type	boolean
Default	false

theme optional
Description	Custom color scheme. If undefined, inherits default Tweakpane theme equivalent to ThemeUtils.presets.standard, or the theme set with setGlobalDefaultTheme().
Type	Theme
Default	undefined

label optional
Description	Text displayed next to control.
Type	string
Default	undefined

value bindablerequired
Description	Image data as Base64-encoded string, or undefined to clear.
Type	ImageValue

extensions optional
Description	Array of image extension types to accept.
Type	string[]
Default	['.jpg', '.png', '.gif']

fit optional
Description	How to display the image in the preview pane. Renamed from imageFit in tweakpane-image-plugin for concision.
Type	'contain' | 'cover'
Default	'cover'

---

Events

change
Description	Fires when value changes. This event is provided for advanced use cases. It's usually preferred to bind to the value prop instead. The event.details payload includes a copy of the value and an origin field to distinguish between user-interactive changes (internal) and changes resulting from programmatic manipulation of the value (external).
Extends	ValueChangeEvent
Type	ImageChangeEvent