React गाइड

@reelkit/react से स्लाइडर बनाना सीखें।

Reel कंपोनेंट

Reel कंपोनेंट मुख्य कंटेनर है। यह स्लाइडर की स्टेट संभालता है और टच जेस्चर, कीबोर्ड नेविगेशन और एनिमेशन को हैंडल करता है।

DOM में हमेशा सिर्फ़ तीन स्लाइड रहती हैं, मौजूदा और उसके दोनों पड़ोसी, इसलिए दस हज़ार आइटम की सूची की लागत दस आइटम की सूची जितनी ही होती है। इसे पूरी फ़ीचर में काम करते देखने के लिए, जैसे इनफ़िनिट फ़ीड या प्लेयर खोलने वाला ग्रिड, रेसिपी देखें।

import { Reel, ReelIndicator } from '@reelkit/react';

<Reel
  count={items.length}
  size={[width, height]}
  direction="vertical"
  enableWheel
  afterChange={(index) => console.log('Current:', index)}
  itemBuilder={(index, indexInRange, size) => (
    <div style={{ width: size[0], height: size[1] }}>
      Slide {index}
    </div>
  )}
>
  {/* Optional children like ReelIndicator */}
</Reel>

अपने-आप साइज़

size prop वैकल्पिक है। इसे छोड़ने पर Reel ResizeObserver से अपना कंटेनर खुद नापता है और CSS से तय लेआउट के हिसाब से ढल जाता है। कंटेनर का साइज़ उसके parent से तय होना चाहिए (जैसे flex, grid या तय CSS आकार)।

// Explicit size (fixed)
<Reel count={items.length} size={[400, 600]} itemBuilder={...} />

// Auto-size (responsive — sized by CSS)
<Reel count={items.length} style={{ width: '100%', height: '100dvh' }} itemBuilder={...} />

itemBuilder पैटर्न

itemBuilder prop एक फ़ंक्शन है जो index लेता है और हर स्लाइड का कंटेंट लौटाता है। इसी पैटर्न से वर्चुअलाइज़ेशन संभव होता है — सिर्फ़ दिखने वाले आइटम ही रेंडर होते हैं।

itemBuilder={(index, indexInRange, size) => {
  // index: actual item index (0 to count-1)
  // indexInRange: position in visible window (0, 1, or 2)
  // size: [width, height] of the container
  return <Slide index={index} />;
}}

नेविगेशन

नेविगेशन के बिल्ट-इन तरीके:

import { useRef } from 'react';
import { Reel, type ReelApi } from '@reelkit/react';

function App() {
  const apiRef = useRef<ReelApi>(null);

  return (
    <>
      <Reel
        count={10}
        size={[400, 600]}
        apiRef={apiRef}
        itemBuilder={(index) => <Slide index={index} />}
      />
      <button onClick={() => apiRef.current?.prev()}>Prev</button>
      <button onClick={() => apiRef.current?.next()}>Next</button>
      <button onClick={() => apiRef.current?.goTo(5)}>Go to 5</button>
    </>
  );
}

URL स्टेट

useOverlayUrlState किसी overlay के लिए URL-स्टेट कंट्रोलर बनाकर पूरा लौटाता है, फिर आप उसे किसी *UrlOverlay को उसके controller prop के रूप में देते हैं। खुले होने की स्टेट URL के पास है, इसलिए जुड़ा हुआ overlay खुद खुलता है और आम तौर पर लिंक ही उसे खोलता है। न मौजूद parameter का पहला write history में एक entry जोड़ता है और उसके बाद हर write उसे बदल देता है, इसलिए पेज बदलना back बटन को कभी दबाता नहीं। value/position पढ़ने और प्रोग्राम से चलाने के लिए कंट्रोलर रखें: set(position) खोलता है, set(null) बंद करता है, और set वही निचले स्तर का write है जो overlay स्लाइड बदलने पर अंदर से करता है।

import { useOverlayUrlState, urlIndexKey } from '@reelkit/react';
import { useReactRouterUrlAdapter } from '@reelkit/react/react-router-url-adapter';
import { LightboxUrlOverlay } from '@reelkit/react-lightbox';
import { Link } from 'react-router-dom';

const photo = useOverlayUrlState({
  param: 'photo',
  ...urlIndexKey(() => images.length),
});

// Opening is a link — the overlay reads the URL and opens itself.
<Link to="?photo=3"><img src={images[3].src} /></Link>
<LightboxUrlOverlay controller={photo} images={images} />

// Read the url-derived state, or close programmatically (a low-level write).
photo.position.value; // 3 for ?photo=3, null when nothing is open
photo.set(null); // close

// Routed app: pass a router-backed adapter, otherwise the router's
// own location goes stale and its next navigation drops the param.
const adapter = useReactRouterUrlAdapter();
const routed = useOverlayUrlState({
  param: 'photo',
  adapter,
  ...urlIndexKey(() => images.length),
});

विकल्पों का object param, codec और locator (तीनों ज़रूरी) लेता है, साथ में वैकल्पिक adapter। param और adapter पहले रेंडर पर पढ़े जाते हैं और उसके बाद तय रहते हैं — बदलने के लिए दोबारा mount करें — जबकि codec और locator हर बार ताज़ा पढ़े जाते हैं, इसलिए सूची बढ़ने या क्रम बदलने के बाद की खोज मौजूदा सूची देखती है। codec और locator एक ही Id साझा करने वाली मेल खाती जोड़ी हैं, इसलिए साथ चलते हैं — साधारण ?photo=3 गैलरी के लिए ...urlIndexKey(() => images.length) spread करें, जो दोनों हिस्से एक साथ लौटाता है। urlIndexKey parameter को स्लाइड index से जोड़ता है और उसे getter की लौटाई मौजूदा गिनती तक सीमित रखता है, इसलिए पुराना या सीमा से बाहर का ?photo=99 ठुकराया जाता है और कभी नाम न ली गई स्लाइड खोलने के बजाय URL से अपने-आप हट जाता है। संख्या नहीं, getter पास करें, ताकि पेज वाली फ़ीड बढ़ने पर भी सीमा सही रहे। यह createIndexLocator (locator वाला हिस्सा) को लपेटकर indexCodec के साथ जोड़ता है। पेज वाली फ़ीड या पहचान से key होने वाली गैलरी इसकी जगह अपनी मेल खाती codec + locator जोड़ी देती है। विकल्पों की पूरी तालिका React API रेफ़रेंस में है।

ReelIndicator

एक वैकल्पिक कंपोनेंट, जो Instagram जैसे प्रोग्रेस इंडिकेटर दिखाता है कि आप स्लाइडर में अभी किस जगह पर हैं। Reel के अंदर रखने पर यह context के ज़रिए parent की count और active values से अपने-आप जुड़ जाता है — हाथ से स्टेट जोड़ने की ज़रूरत नहीं।

import { Reel, ReelIndicator } from '@reelkit/react';

{/* Auto-connect: count and active are inherited from parent Reel */}
<Reel count={10} size={[400, 600]} itemBuilder={...}>
  <ReelIndicator />
</Reel>

{/* Manual usage: pass count and active explicitly (e.g. outside a Reel) */}
<ReelIndicator count={10} active={currentIndex} />

मुख्य बातें

• size prop

  वैकल्पिक [width, height] tuple, या CSS से अपने-आप साइज़ के लिए छोड़ दें

• itemBuilder

  index लेता है और स्लाइड का कंटेंट लौटाता है

• apiRef

  नेविगेशन के लिए कंट्रोलर के मेथड तक पहुँच

• afterChange

  UI अपडेट के लिए मौजूदा index पर नज़र रखें

परफ़ॉर्मेंस टिप्स

• डेटा arrays को memoize करें

  अपने आइटम के array को useMemo में लपेटें। हर रेंडर पर नया array reference count अपडेट करवाता है और दिखने वाली ranges दोबारा निकलवाता है।

• itemBuilder को हल्का रखें

  यह दिखने वाली range के हर बदलाव पर चलता है (आम तौर पर 3 स्लाइड)। इसके अंदर भारी गणना या side effects से बचें।

• किनारे के पास डेटा लोड करें

  afterChange से पहचानें कि यूज़र आख़िर के पास पहुँच रहा है, और स्लाइड ख़त्म होने से पहले अगला बैच fetch करें (इनफ़िनिट फ़ीड रेसिपी देखें)।

• स्क्रॉल होने वाले पेज में व्हील बंद करें

  जब स्लाइडर स्क्रॉल होने वाले लेआउट के अंदर हो, तो पेज का स्क्रॉल पकड़ने से बचने के लिए enableWheel={false} सेट करें।