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

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

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

function Gallery() {
  const vistaRef = useRef<VistaInterface>(null);

  return (
    <>
      <VistaView ref={vistaRef} selector="> a">
        <a href="/images/full.jpg">
          <img src="/images/thumb.jpg" alt="Photo" />
        </a>
      </VistaView>
      <button onClick={() => vistaRef.current?.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 } 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) => console.log('Gallery opened'),
  onClose: (vistaView) => 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>
  );
}

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 { useId } from 'react';
import { useVistaView } from 'vistaview/react';
import 'vistaview/style.css';

function Gallery() {
  const id = useId();
  const vista = useVistaView({
    elements: `#${CSS.escape(id)} a`,
  });

  return (<>
    <div id={id}>
      <a href="/images/full.jpg">
        <img src="/images/thumb.jpg" alt="Photo" />
      </a>
    </div>
    <button onClick={() => vista.open(0)}>Open Gallery</button>
    <button onClick={() => vista.next()}>Next</button>
    <button onClick={() => vista.prev()}>Previous</button>
  </>);
}

With Extensions

'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>
  );
}

Next Steps

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