Getting Started with React

VistaView provides official React bindings that offer both declarative components and hooks for React applications.

Installation

npm

npm install vistaview

yarn

yarn add vistaview

pnpm

pnpm add vistaview

bun

bun add vistaview

Component Approach (Recommended)

The VistaView component provides a declarative way to create image galleries:

'use client'; // Required for Next.js and other React Server Components frameworks

import { VistaView } from 'vistaview/react';
import 'vistaview/style.css';

function Gallery() {
  return (
    <VistaView selector="> a">
      <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>
  );
}

With Ref for Imperative Control

We expose the API and root container on the component ref as { vistaView, container }.

💡 Types: You can import VistaComponentRef from vistaview/react (see the Type Reference):

'use client'; // Required for Next.js and other React Server Components frameworks

import { useRef } from 'react';
import { VistaView } from 'vistaview/react';
import type { VistaComponentRef } from 'vistaview/react';
import 'vistaview/style.css';

function Gallery() {
  const compRef = useRef<VistaComponentRef>(null);

  return (
    <>
      <VistaView ref={compRef} selector="> a">
        <a href="/images/full.jpg">
          <img src="/images/thumb.jpg" alt="Photo" />
        </a>
      </VistaView>
      <button onClick={() => compRef.current?.vistaView?.open(0)}>Open Gallery</button>
    </>
  );
}

With Options

'use client'; // Required for Next.js and other React Server Components frameworks

import { VistaView } from 'vistaview/react';
import type { VistaOpt, VistaView } from 'vistaview';
import 'vistaview/style.css';

// Define options outside component to prevent recreation on every render
const options: VistaOpt = {
  maxZoomLevel: 3,
  preloads: 2,
  animationDurationBase: 400,
  onOpen: (vistaView: VistaView): void => {
    console.log('Gallery opened');
  },
  onClose: (vistaView: VistaView): void => {
    console.log('Gallery closed');
  },
};

function Gallery() {
  return (
    // selector defaults to '> a'
    <VistaView options={options}>
      <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>
  );
}

With Extensions

'use client'; // Required for Next.js and other React Server Components frameworks

import { VistaView } from 'vistaview/react';
import { download } from 'vistaview/extensions/download';
import 'vistaview/style.css';

// Define options outside component to prevent recreation on every render
const extensionOptions = {
  controls: {
    topRight: ['zoomIn', 'zoomOut', 'download', 'close'],
  },
  extensions: [download()],
};

function Gallery() {
  return (
    <VistaView
      selector="> a"
      options={extensionOptions}
    >
      <a href="/images/photo1.jpg">
        <img src="/images/photo1-thumb.jpg" alt="Photo 1" />
      </a>
    </VistaView>
  );
}

Hook Approach

Use the useVistaView hook for more control over the gallery instance:

'use client'; // Required for Next.js and other React Server Components frameworks

import { useVistaView } from 'vistaview/react';
import { download } from 'vistaview/extensions/download';
import 'vistaview/style.css';

function Gallery() {
  const vista = useVistaView({
    elements: '#gallery > a',
    controls: {
      topRight: ['zoomIn', 'zoomOut', 'download', 'close'],
    },
    extensions: [download()],
  });

  return (
    <div id="gallery">
      <a href="/images/photo1.jpg">
        <img src="/images/photo1-thumb.jpg" alt="Photo 1" />
      </a>
    </div>
  );
}

Type Reference

VistaViewProps

interface VistaViewProps {
  children: ReactNode;
  selector?: string; // defaults to "> a"
  options?: VistaOpt; // passes through to core options
  ref?: React.Ref<VistaComponentRef>;
}

• children: The gallery markup (usually <a><img/></a> items).
• selector: CSS selector used to locate items inside the container.
• options: Configuration passed to the core VistaView instance (VistaOpt).
• ref: React ref that receives a VistaComponentRef for imperative control.

VistaComponentRef

type VistaComponentRef = { 
  vistaView: VistaInterface | null; 
  container: HTMLDivElement | null 
} | null;

• vistaView: The runtime API instance (VistaInterface) — use it to call .open(), .next(), .prev(), .zoomIn(), .zoomOut(), .close(), .destroy(), etc.
• container: The root DOM element that wraps the gallery — useful for queries or DOM measurements.

Related types

• VistaOpt — core configuration object (see /core/configuration/complete or main/src/lib/types.ts for full shape).
• VistaInterface — runtime API methods available on vistaView.

Import example

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

Next Steps

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