Getting Started with Svelte

VistaView provides a VistaView Svelte component (recommended) and a lower-level useVistaView hook for advanced use cases.

Installation

npm

npm install vistaview

yarn

yarn add vistaview

pnpm

pnpm add vistaview

bun

bun add vistaview

Component-first usage (recommended)

The recommended, primary way to use VistaView in Svelte is the VistaView component. It handles lifecycle, DOM changes, and provides a simple imperative API via bind:this and getApi().

Basic example

<script>
import { VistaView } from 'vistaview/svelte';
import 'vistaview/style.css';

let comp;
</script>

<VistaView bind:this={comp}>
  <a href="/images/photo1-full.jpg">
    <img src="/images/photo1-thumb.jpg" alt="Photo 1" />
  </a>
  <a href="/images/photo2-full.jpg">
    <img src="/images/photo2-thumb.jpg" alt="Photo 2" />
  </a>
</VistaView>

<button on:click={() => comp?.getApi()?.vistaView?.open(0)}>Open Gallery</button>

Imperative Control

If you need programmatic access to the gallery API, use the vistaRef callback prop:

<script>
import { VistaView } from 'vistaview/svelte';
import type { VistaInterface } from 'vistaview';
import 'vistaview/style.css';

let vista: VistaInterface | null = null;
let container: HTMLElement | null = null;
</script>

<VistaView vistaRef={(api) => {
  vista = api?.vistaView ?? null;
  container = api?.container ?? null;
}}>
  <a href="/images/full.jpg"><img src="/images/thumb.jpg" alt="Photo" /></a>
</VistaView>

<button on:click={() => vista?.open(0)}>Open Gallery</button>
<button on:click={() => vista?.next()}>Next</button>
<button on:click={() => vista?.prev()}>Previous</button>
<button on:click={() => console.log(container)}>Log Container</button>

Options

<script>
import { VistaView } from 'vistaview/svelte';
import type { VistaOpt } from 'vistaview';
import 'vistaview/style.css';

const options: VistaOpt = {
  maxZoomLevel: 3,
  preloads: 2,
  animationDurationBase: 400,
  onOpen: (vistaView) => console.log('Gallery opened'),
  onClose: (vistaView) => console.log('Gallery closed'),
};
</script>

<VistaView options={options}>
  <a href="/images/photo1-full.jpg"><img src="/images/photo1-thumb.jpg" alt="Photo 1" /></a>
</VistaView>

Extensions

<script>
import { VistaView } from 'vistaview/svelte';
import { download } from 'vistaview/extensions/download';
import 'vistaview/style.css';

const options = { controls: { topRight: ['zoomIn','zoomOut','download','close'] }, extensions: [download()] };
</script>

<VistaView options={options}>
  <a href="/images/photo1.jpg"><img src="/images/photo1-thumb.jpg" alt="Photo 1" /></a>
</VistaView>

Tip: prefer the component when your gallery content is dynamic, as it observes DOM changes and re-initializes automatically.

Hook approach (advanced)

The useVistaView hook is a lower-level API. Use it for non-component contexts or when you need manual control. The hook handles lifecycle internally (onMount/onDestroy), so you can call it at the top level.

<script>
import { useVistaView } from 'vistaview/svelte';
import 'vistaview/style.css';

const vista = useVistaView({ elements: '#my-gallery > a' });
</script>

<div id="my-gallery">
  <a href="/images/photo1.jpg">
    <img src="/images/photo1-thumb.jpg" alt="Photo 1" />
  </a>
</div>

<button on:click={() => vista?.open?.(0)}>Open</button>

Low-level usage

You can call the core vistaView function directly when embedding in non-component contexts:

<script>
import { onMount } from 'svelte';
import { vistaView } from 'vistaview';
import 'vistaview/style.css';

let instance;

onMount(() => {
  instance = vistaView({ elements: '#my-gallery > a' });
  return () => instance?.destroy();
});
</script>

SvelteKit

Use the VistaView component in SvelteKit apps; it handles lifecycle and DOM updates automatically. If you need the hook, initialize it inside onMount to avoid SSR issues.

Types

import type { VistaViewProps, VistaComponentRef } from 'vistaview/svelte';

Best practices & troubleshooting

• Prefer the component for most cases (dynamic content, SvelteKit, simpler lifecycle).
• Keep options objects stable (define outside render scope) to avoid unnecessary re-initializations.
• Use optional chaining (e.g., comp?.getApi()?.vistaView?.open(0)) when calling methods that may not be ready yet.
• If using the hook and the DOM changes dynamically, re-initialize or prefer the component.

Next Steps

• Explore configuration options
• Learn about extensions
• Customize the styling