React API रेफ़रेंस

@reelkit/react के कंपोनेंट, props और मेथड का पूरा रेफ़रेंस।

Reel के props

ReelProps

Prop	टाइप	डिफ़ॉल्ट	विवरण
`count`	`number`	ज़रूरी	आइटम की कुल संख्या
`size`	`[number, number]`	-	[width, height] के रूप में चौड़ाई और ऊँचाई। छोड़ने पर ResizeObserver से अपने-आप नापता है
`itemBuilder`	`(index, indexInRange, size) => ReactElement`	ज़रूरी	हर स्लाइड रेंडर करने वाला फ़ंक्शन
`direction`	`'vertical' \| 'horizontal'`	'vertical'	स्क्रॉल की दिशा
`initialIndex`	`number`	0	शुरुआती index
`loop`	`boolean`	false	अनंत लूप चालू करता है
`enableWheel`	`boolean`	false	माउस व्हील से नेविगेशन चालू करता है
`wheelDebounceMs`	`number`	200	ms में व्हील इवेंट का debounce
`enableNavKeys`	`boolean`	true	कीबोर्ड नेविगेशन चालू करता है
`onNavKeyPress`	`(increment: -1 \| 1) => void`	-	तीर वाली कुंजियों से नेविगेशन का कस्टम हैंडलर। डिफ़ॉल्ट prev/next व्यवहार की जगह लेता है।
`transition`	`TransitionTransformFn`	slideTransition	ट्रांज़िशन इफ़ेक्ट का फ़ंक्शन। बिल्ट-इन: slideTransition, fadeTransition, flipTransition, cubeTransition, zoomTransition
`transitionDuration`	`number`	300	ms में एनिमेशन की अवधि
`enableGestures`	`boolean`	true	टच/माउस से खींचकर नेविगेशन चालू करता है
`swipeDistanceFactor`	`number`	0.12	स्वाइप की सीमा (0-1)
`rangeExtractor`	`(index: number, count: number) => number[]`	defaultRangeExtractor	कौन-से index रेंडर हों, यह तय करने वाला कस्टम फ़ंक्शन
`keyExtractor`	`(index: number) => string`	-	React reconciliation के लिए कस्टम key फ़ंक्शन (loop के साथ काम का)
`apiRef`	`RefObject<ReelApi>`	-	API मेथड तक पहुँचने के लिए ref
`className`	`string`	-	कंटेनर एलिमेंट की CSS class
`style`	`CSSProperties`	-	कंटेनर एलिमेंट की inline styles
`ariaLabel`	`string`	-	carousel क्षेत्र का सुलभ लेबल, जिसे स्क्रीन रीडर पढ़ते हैं

Callbacks

Prop	टाइप	विवरण
`afterChange`	`(index, indexInRange) => void`	स्लाइड बदलना पूरा होने के बाद कॉल होता है
`beforeChange`	`(index, nextIndex, indexInRange) => void`	स्लाइड बदलना शुरू होने से पहले कॉल होता है
`onSlideDragStart`	`(index) => void`	खींचने का जेस्चर शुरू होने पर कॉल होता है
`onSlideDragEnd`	`(index) => void`	खींचने का जेस्चर ख़त्म होने पर कॉल होता है
`onSlideDragCanceled`	`(index) => void`	खींचना रद्द होने पर कॉल होता है

ReelApi के मेथड

apiRef के ज़रिए स्लाइडर के मेथड तक पहुँचें:

typescript

const apiRef = useRef<ReelApi>(null);

// Navigation
apiRef.current?.next();
apiRef.current?.prev();
apiRef.current?.goTo(5);           // instant
apiRef.current?.goTo(5, true);     // animated

// Lifecycle
apiRef.current?.adjust();          // recalculate positions
apiRef.current?.observe();         // start observing keyboard
apiRef.current?.unobserve();       // stop observing keyboard

मेथड	टाइप	विवरण
`next()`	`() => void`	अगली स्लाइड पर जाता है
`prev()`	`() => void`	पिछली स्लाइड पर जाता है
`goTo(index, animate?)`	`(number, boolean?) => Promise`	किसी खास स्लाइड पर जाता है
`adjust()`	`() => void`	स्लाइड की स्थितियाँ दोबारा निकालता है
`observe()`	`() => void`	कीबोर्ड पर नज़र रखना शुरू करता है
`unobserve()`	`() => void`	कीबोर्ड पर नज़र रखना बंद करता है

ReelIndicator के props

ReelIndicatorProps

Prop	टाइप	डिफ़ॉल्ट	विवरण
`count`	`number`	auto	आइटम की कुल संख्या। parent Reel के अंदर होने पर उससे अपने-आप जुड़ती है; अकेले इस्तेमाल करने पर साफ़ तौर पर पास करें
`active`	`number`	auto	मौजूदा सक्रिय index। parent Reel के अंदर होने पर उससे अपने-आप जुड़ता है; अकेले इस्तेमाल करने पर साफ़ तौर पर पास करें
`direction`	`'vertical' \| 'horizontal'`	'vertical'	इंडिकेटर की दिशा
`radius`	`number`	3	पिक्सेल में बिंदु का आकार
`visible`	`number`	5	दिखने वाले सामान्य आकार के बिंदुओं की अधिकतम संख्या
`gap`	`number`	4	पिक्सेल में बिंदुओं के बीच की दूरी
`activeColor`	`string`	'#fff'	सक्रिय बिंदु का रंग
`inactiveColor`	`string`	'rgba(255,255,255,0.5)'	निष्क्रिय बिंदु का रंग
`edgeScale`	`number`	0.5	किनारे पर overflow वाले बिंदुओं का scale
`onDotClick`	`(index: number) => void`	-	बिंदु पर क्लिक होने पर callback
`className`	`string`	-	कस्टम CSS class
`style`	`CSSProperties`	-	कस्टम inline styles

Observer कंपोनेंट

Observe

core signals को React रेंडरिंग से जोड़ता है, parent को दोबारा रेंडर किए बिना। subscribe किए गए signals बदलने पर सिर्फ़ children फ़ंक्शन दोबारा चलता है।

tsx

import { Observe } from '@reelkit/react';

<Observe signals={[controller.state.index]}>
  {() => <span>Current: {controller.state.index.value}</span>}
</Observe>

Prop	टाइप	डिफ़ॉल्ट	विवरण
`signals`	`Subscribable[]`	`required`	जिन signals को subscribe करना है। इनमें से किसी की भी सूचना children फ़ंक्शन को दोबारा चलाती है — और सिर्फ़ उसी को, parent को कभी नहीं। बाद के render में दिया गया अलग signal, जिसकी जगह वह लेता है उसके बदले follow किया जाता है।
`children`	`() => ReactElement \| null`	`required`	रेंडर फ़ंक्शन, जो हर बदलाव पर दोबारा चलता है। signal के मान इसके अंदर पढ़ें; बाहर पढ़ा गया मान एक बार पकड़ा जाता है और पुराना पड़ जाता है।

AnimatedObserve

एनिमेटेड value signals को subscribe करता है और requestAnimationFrame से धीरे-धीरे बीच के मान निकालता है।

tsx

import { AnimatedObserve } from '@reelkit/react';

<AnimatedObserve signal={controller.state.axisValue}>
  {(value) => (
    <div style={{ transform: `translateY(${value}px)` }} />
  )}
</AnimatedObserve>

Prop	टाइप	डिफ़ॉल्ट	विवरण
`signal`	`Signal<AnimatedValue>`	`required`	{ value, duration, done? } देने वाला signal। 0 से ज़्यादा अवधि मौजूदा मान से नए मान तक बीच के मान निकालती है; 0 सीधे वहीं पहुँचा देता है।
`children`	`(value: number) => ReactElement`	`required`	मौजूदा फ़्रेम का निकाला गया मान लेने वाला रेंडर फ़ंक्शन, जो synchronous रूप से लागू होता है ताकि DOM एनिमेशन के साथ चले।

SwipeToClose

<SwipeToClose> अपने children को ऐसे कंटेनर में रखता है जो vertical स्वाइप के साथ चलता है और स्वाइप के सीमा पार करते ही onClose कॉल करता है — lightbox और stories player का बंद करने वाला जेस्चर, आपके अपने कस्टम overlay के लिए। SwipeToCloseProps इसके props को टाइप करता है; SwipeToCloseDirection 'up' | 'down' है।

Prop	टाइप	डिफ़ॉल्ट	विवरण
`direction`	`SwipeToCloseDirection`	ज़रूरी	`'up'` lightbox की तरह बंद करता है, `'down'` stories player की तरह
`onClose`	`() => void`	ज़रूरी	स्वाइप के सीमा पार करने और बाहर जाने का एनिमेशन ख़त्म होने के बाद कॉल होता है
`enabled`	`boolean`	`true`	unmount किए बिना जेस्चर बंद करता है
`threshold`	`number`	`0.2`	viewport की ऊँचाई का वह हिस्सा जितना स्वाइप को तय करना है
`className`	`string`	—	बाहरी `<div>` पर class
`children`	`ReactNode`	ज़रूरी	स्वाइप के साथ चलने वाला कंटेंट

SoundProvider

<SoundProvider> एक SoundController बनाता है, शुरू में muted, और उसे useSoundState के ज़रिए अपने children को देता है। overlays एक provider ख़ुद रेंडर करते हैं; अपना सिर्फ़ ऐसे कस्टम प्लेयर के आसपास जोड़ें जिसके कंट्रोल एक ही mute स्टेट साझा करते हों।

Hooks

useBodyLock

body का स्क्रॉल lock करता है और scrollbar की चौड़ाई से होने वाले खिसकाव की भरपाई करता है।

typescript

import { useBodyLock } from '@reelkit/react';

// Lock body scroll when overlay is open
useBodyLock(isOpen);

useOverlayUrlState

OverlayUrlStateOptions

किसी overlay के लिए URL-स्टेट कंट्रोलर बनाता है, जिसे आप किसी *UrlOverlay को उसके controller prop के रूप में देते हैं।

पूरी जानकारी और उदाहरणों के लिए React गाइड में URL स्टेट देखें।

विकल्प	टाइप	डिफ़ॉल्ट	विवरण
`param`	`string`	ज़रूरी	सक्रिय स्लाइड रखने वाला query parameter, जैसे "photo"। पहले रेंडर पर पढ़ा जाता है और कंपोनेंट के पूरे जीवन में तय रहता है — बदलने के लिए दोबारा mount करें (उसे key दें)।
`adapter`	`UrlAdapter`	History API	पढ़ने और लिखने के लिए नेविगेशन सिस्टम। routing वाले ऐप में router पर आधारित adapter पास करें, ताकि router की अपनी location पुरानी न पड़े। पहले रेंडर पर पढ़ा जाता है और कंपोनेंट के पूरे जीवन में तय रहता है — बदलने के लिए दोबारा mount करें।
`codec`	`{ decode(raw) => Id \| null; encode(id) => string }`	ज़रूरी	wire का रूप: parameter का टेक्स्ट ↔ स्थिर पहचान, collection से बेख़बर। एक ही Id साझा करने वाली मेल खाती जोड़ी के रूप में locator के साथ चलता है — डिफ़ॉल्ट ?photo=3 index गैलरी के लिए ...urlIndexKey(() => images.length) spread करें, या अपना (base64, slug) दें ताकि गैलरी का क्रम बदलने पर भी bookmark काम करे। हर बार ताज़ा पढ़ा जाता है: अगला decode या encode आख़िरी रेंडर का codec करता है।
`locator`	`{ locate(id) => number \| null; locateAsync?(id) => Promise<number \| null>; identify(index) => id }`	ज़रूरी	पहचान को स्थिति से जोड़ता है और उसकी वैधता खुद संभालता है: locate (sync), locateAsync (पेज वाली गैलरी के लिए async विकल्प), identify (writes)। साधारण index गैलरी के लिए ...urlIndexKey(() => images.length) spread करें — यह यह locator और मेल खाता codec देता है और ?photo=3 को मौजूदा गिनती तक सीमित रखता है, इसलिए पुराना ?photo=99 कभी नाम न ली गई स्लाइड खोलने के बजाय URL से अपने-आप हट जाता है। पेज वाली फ़ीड या पहचान से key होने वाली गैलरी इसकी जगह अपनी मेल खाती codec + locator जोड़ी देती है। हर बार ताज़ा पढ़ा जाता है: अगली खोज का जवाब आख़िरी रेंडर का locator देता है, और रेंडरों के बीच locateAsync जोड़ना या हटाना अगली बार न मिलने पर लागू होता है।

useReactRouterUrlAdapter

React Router पर आधारित UrlAdapter। routing वाले ऐप में इसे useOverlayUrlState के adapter विकल्प के रूप में पास करें, ताकि नेविगेशन की सच्चाई का अकेला स्रोत router ही रहे — router के पीछे history.pushState लिखने से उसकी location पुरानी पड़ जाती है और उसका अगला नेविगेशन parameter गिरा देता है। Writes सिर्फ़ query को छूते हैं, इसलिए pathname और hash बिना बदले साथ चलते हैं। हर बदलाव बताता है कि router ने उसी पेज पर push किया, replace किया या history में आगे-पीछे गया, इसलिए <Link> से खुली गैलरी back के एक कदम से बंद होती है।

यह अपने अलग subpath से आता है, इसलिए बिना router वाला ऐप react-router-dom को कभी अपने बंडल में नहीं खींचता। react-router-dom एक वैकल्पिक peer dependency है।

tsx

import { useReactRouterUrlAdapter } from '@reelkit/react/react-router-url-adapter';

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

useReelContext

useReelContext() सबसे पास वाले पैरेंट <Reel> का ReelContextValue पढ़ता है, या उसके बाहर null लौटाता है। <ReelIndicator> ख़ुद को जोड़ने के लिए इसी का इस्तेमाल करता है; इसे <Reel> के children के रूप में रेंडर होने वाले अपने कंट्रोल में इस्तेमाल करें, ताकि वे बिना props के स्लाइडर के साथ चलें। ReelContext इसके पीछे का context ऑब्जेक्ट है — अपना मान सिर्फ़ किसी टेस्ट या कस्टम wrapper में दें।

प्रॉपर्टी	टाइप	विवरण
`index`	`Signal<number>`	सक्रिय स्लाइड का index; `.value` को `Observe` के अंदर पढ़ें
`count`	`Signal<number>`	स्लाइडों की कुल संख्या
`goTo`	`(index: number, animate?: boolean) => Promise<void>`	किसी स्लाइड पर जाता है, एनिमेशन के साथ या बिना

useSoundState

useSoundState() सबसे पास वाले <SoundProvider> से SoundController पढ़ता है और उसके बाहर एरर देता है। reel player, lightbox और stories player अपना कंटेंट एक provider में रखते हैं, इसलिए उनके render props से दिए गए कस्टम कंट्रोल इसे mute पढ़ने या टॉगल करने के लिए कॉल कर सकते हैं।

useFullscreen

useFullscreen({ ref }) ref वाले एलिमेंट के लिए Fullscreen API चलाता है, और कंपोनेंट unmount होने पर फ़ुलस्क्रीन से बाहर आता है। UseFullscreenProps इसका argument है; UseFullscreenResult वह tuple है जो यह लौटाता है।

Index	टाइप	विवरण
`[0]`	`Signal<boolean>`	पेज फ़ुलस्क्रीन में है या नहीं; `.value` को `Observe` के अंदर पढ़ें
`[1]`	`() => Promise<void>`	एलिमेंट के लिए फ़ुलस्क्रीन माँगता है, पहले किसी दूसरे फ़ुलस्क्रीन एलिमेंट से बाहर आकर
`[2]`	`() => Promise<void>`	फ़ुलस्क्रीन से बाहर आता है
`[3]`	`() => Promise<void>`	दोनों के बीच टॉगल करता है

सुलभता

<Reel> aria-roledescription="carousel" के साथ role="region" के रूप में रेंडर होता है। क्षेत्र को स्क्रीन रीडर के लिए नाम देने के लिए ariaLabel prop सेट करें। एक polite live region हर स्लाइड बदलने पर carousel को दोबारा रेंडर किए बिना "Slide N of M" बोलता है। निष्क्रिय स्लाइडों को inert attribute मिलता है, ताकि फ़ोकस और सहायक तकनीक का नेविगेशन उन्हें छोड़ दे।

<ReelIndicator> बिंदुओं पर roving tabindex के साथ role="tablist" के रूप में रेंडर होता है; तीर वाली कुंजियाँ फ़ोकस खिसकाती हैं और Enter या Space स्लाइड सक्रिय करता है।

<Reel> के आसपास अपना modal बना रहे हैं? फ़ोकस लौटाने और रोकने के लिए captureFocusForReturn, createFocusTrap और getFocusableElements @reelkit/react से भी export होते हैं।

यूटिलिटी

createDefaultKeyExtractorForLoop

ऐसा key extractor बनाता है जो loop चालू होने पर दोहराए गए index संभालता है।

tsx

import { createDefaultKeyExtractorForLoop } from '@reelkit/react';

<Reel
  count={items.length}
  size={size}
  loop
  keyExtractor={createDefaultKeyExtractorForLoop(items.length)}
  itemBuilder={...}
/>

साइज़ पहचान

observeElementSize, getViewportSize, observeViewportSize, isMobileWidth, fitAspectRatio और isTouchDevice @reelkit/react से re-export होते हैं, ऐसे कस्टम overlay के लिए जो reelkit वालों की तरह अपना साइज़ तय करे। core API में साइज़ पहचान देखें।

ऑटोप्ले और डाउनलोड

createTimerController, createSlideshowController और downloadFile भी @reelkit/react से re-export होते हैं: stories players के पीछे का टाइमर, lightbox के autoAdvance के पीछे का स्लाइडशो, और उसके डाउनलोड बटन के पीछे का helper। core API में ऑटोप्ले और डाउनलोड देखें।