From 2792f02a495f683392ccfef99814265cd8fb37e0 Mon Sep 17 00:00:00 2001
From: Meir Roth <12494197+meirroth@users.noreply.github.com>
Date: Mon, 22 Apr 2024 15:29:31 +0300
Subject: [PATCH] chore(docs): note about reactive options

Co-authored-by: David Jerleke <david.jerleke@gmail.com>
Co-authored-by: Meir Roth <12494197+meirroth@users.noreply.github.com>
---
 .../src/content/pages/api/events.mdx          |  24 ++--
 .../src/content/pages/api/methods.mdx         |  16 +--
 .../src/content/pages/api/options.mdx         | 112 +++++++++++++++++-
 .../src/content/pages/api/plugins.mdx         |  16 +--
 .../src/content/pages/get-started/react.mdx   |   2 +
 .../src/content/pages/get-started/solid.mdx   |   8 +-
 .../src/content/pages/get-started/svelte.mdx  |   2 +
 .../src/content/pages/get-started/vue.mdx     |  16 ++-
 8 files changed, 153 insertions(+), 43 deletions(-)

diff --git a/packages/embla-carousel-docs/src/content/pages/api/events.mdx b/packages/embla-carousel-docs/src/content/pages/api/events.mdx
index b1c32d16..8138b6c6 100644
--- a/packages/embla-carousel-docs/src/content/pages/api/events.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/api/events.mdx
@@ -66,7 +66,7 @@ export function EmblaCarousel() {
 
 ```html highlight={12}
 <script setup>
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import emblaCarouselVue from 'embla-carousel-vue'
 
   const [emblaRef, emblaApi] = emblaCarouselVue()
@@ -75,7 +75,7 @@ export function EmblaCarousel() {
     console.log(emblaApi.slidesInView())
   }
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) emblaApi.value.on('slidesInView', logSlidesInView)
   })
 
@@ -87,7 +87,7 @@ export function EmblaCarousel() {
 <TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
 
 ```jsx highlight={13}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import createEmblaCarousel from 'embla-carousel-solid'
 
 export function EmblaCarousel() {
@@ -97,7 +97,7 @@ export function EmblaCarousel() {
     console.log(emblaApi.slidesInView())
   }
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) api.on('slidesInView', logSlidesInView)
   })
@@ -180,7 +180,7 @@ export function EmblaCarousel() {
 
 ```html highlight={9}
 <script setup>
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import emblaCarouselVue from 'embla-carousel-vue'
 
   const [emblaRef, emblaApi] = emblaCarouselVue()
@@ -190,7 +190,7 @@ export function EmblaCarousel() {
     emblaApi.off('slidesInView', logSlidesInViewOnce)
   }
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) emblaApi.value.on('slidesInView', logSlidesInViewOnce)
   })
 
@@ -202,7 +202,7 @@ export function EmblaCarousel() {
 <TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
 
 ```jsx highlight={9}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import createEmblaCarousel from 'embla-carousel-solid'
 
 export function EmblaCarousel() {
@@ -213,7 +213,7 @@ export function EmblaCarousel() {
     emblaApi.off('slidesInView', logSlidesInViewOnce)
   }
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) api.on('slidesInView', logSlidesInViewOnce)
   })
@@ -313,7 +313,7 @@ export function EmblaCarousel() {
 
 ```html highlight={3,10}
 <script setup>
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import { EmblaCarouselType, EmblaEventType } from 'embla-carousel'
   import emblaCarouselVue from 'embla-carousel-vue'
 
@@ -326,7 +326,7 @@ export function EmblaCarousel() {
     console.log(`Embla just triggered ${eventName}!`)
   }
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) emblaApi.value.on('slidesInView', logEmblaEvent)
   })
 
@@ -346,7 +346,7 @@ export function EmblaCarousel() {
 <TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
 
 ```jsx highlight={2,10}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import { EmblaCarouselType, EmblaEventType } from 'embla-carousel'
 import createEmblaCarousel from 'embla-carousel-solid'
 
@@ -360,7 +360,7 @@ export function EmblaCarousel() {
     console.log(`Embla just triggered ${eventName}!`)
   }
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) api.on('slidesInView', logEmblaEvent)
   })
diff --git a/packages/embla-carousel-docs/src/content/pages/api/methods.mdx b/packages/embla-carousel-docs/src/content/pages/api/methods.mdx
index 279e30e0..c33c4217 100644
--- a/packages/embla-carousel-docs/src/content/pages/api/methods.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/api/methods.mdx
@@ -58,12 +58,12 @@ export function EmblaCarousel() {
 
 ```html highlight={8}
 <script setup>
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import emblaCarouselVue from 'embla-carousel-vue'
 
   const [emblaRef, emblaApi] = emblaCarouselVue()
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) console.log(emblaApi.value.slideNodes())
   })
 
@@ -75,13 +75,13 @@ export function EmblaCarousel() {
 <TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
 
 ```jsx highlight={9}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import createEmblaCarousel from 'embla-carousel-solid'
 
 export function EmblaCarousel() {
   const [emblaRef, emblaApi] = createEmblaCarousel()
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) console.log(api.slideNodes())
   })
@@ -167,7 +167,7 @@ export function EmblaCarousel() {
 
 ```html highlight={3,8}
 <script setup lang="ts">
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import { EmblaCarouselType } from 'embla-carousel'
   import emblaCarouselVue from 'embla-carousel-vue'
 
@@ -177,7 +177,7 @@ export function EmblaCarousel() {
     console.log(emblaApi.slidesInView())
   }
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) emblaApi.value.on('slidesInView', logSlidesInView)
   })
 
@@ -197,7 +197,7 @@ export function EmblaCarousel() {
 <TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
 
 ```jsx highlight={2,8}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import { EmblaCarouselType } from 'embla-carousel'
 import createEmblaCarousel from 'embla-carousel-solid'
 
@@ -208,7 +208,7 @@ export function EmblaCarousel() {
     console.log(emblaApi.slidesInView())
   }
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) api.on('slidesInView', logSlidesInView)
   })
diff --git a/packages/embla-carousel-docs/src/content/pages/api/options.mdx b/packages/embla-carousel-docs/src/content/pages/api/options.mdx
index 6d5011b9..fd0e3ffd 100644
--- a/packages/embla-carousel-docs/src/content/pages/api/options.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/api/options.mdx
@@ -88,12 +88,6 @@ export function EmblaCarousel() {
 </TabsItem>
 </Tabs>
 
-<Admonition>
-  Note that it's possible to **change options** passed to the Embla Carousel
-  constructor **after initialization** with the [reInit](/api/methods/#reinit)
-  method.
-</Admonition>
-
 ### Global options
 
 Setting **global options** will be applied to **all carousels** which will override the Embla default options with your own. In the following example [loop](/api/options/#loop) is set to `true`:
@@ -179,6 +173,112 @@ export function EmblaCarousel() {
   code and unexpected behaviour.
 </Admonition>
 
+### Changing options
+
+It's possible to **change options** passed to the Embla Carousel constructor **after initialization** with the [reInit](/api/methods/#reinit) method.
+
+In [React](/get-started/react/), [Vue](/get-started/vue/), [Solid](/get-started/solid/) and [Svelte](/get-started/svelte/) wrappers you can pass **reactive options** and the carousel will automatically reinitialize when they change. Here are some examples:
+
+<Tabs groupId={TABS_LIBRARY.GROUP_ID}>
+<TabsItem tab={TABS_LIBRARY.TABS.VANILLA}>
+
+```js highlight={6}
+import EmblaCarousel from 'embla-carousel'
+
+const emblaNode = document.querySelector('.embla')
+const emblaApi = EmblaCarousel(emblaNode, { loop: true })
+
+emblaApi.reInit({ loop: false })
+```
+
+</TabsItem>
+<TabsItem tab={TABS_LIBRARY.TABS.REACT}>
+
+```jsx highlight={5,9-12}
+import { useState, useCallback } from 'react'
+import useEmblaCarousel from 'embla-carousel-react'
+
+export function EmblaCarousel() {
+  const [options, setOptions] = useState({ loop: true })
+  const [emblaRef, emblaApi] = useEmblaCarousel(options)
+
+  const toggleLoop = useCallback(() => {
+    setOptions((currentOptions) => ({
+      ...currentOptions,
+      loop: !currentOptions.loop
+    }))
+  }, [])
+
+  // ...
+}
+```
+
+</TabsItem>
+<TabsItem tab={TABS_LIBRARY.TABS.VUE}>
+
+```html highlight={4,8-11}
+<script setup>
+  import emblaCarouselVue from 'embla-carousel-vue'
+
+  const options = ref({ loop: true })
+  const [emblaRef, emblaApi] = emblaCarouselVue(options)
+
+  function toggleLoop() {
+    options.value = {
+      ...options.value,
+      loop: !options.value.loop
+    }
+  }
+
+  // ...
+</script>
+```
+
+</TabsItem>
+<TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
+
+```jsx highlight={5,9-12}
+import { createSignal } from 'solid-js'
+import createEmblaCarousel from 'embla-carousel-solid'
+
+export function EmblaCarousel() {
+  const [options, setOptions] = createSignal({ loop: true })
+  const [emblaRef] = createEmblaCarousel(() => options())
+
+  function toggleLoop() {
+    setOptions((currentOptions) => ({
+      ...currentOptions,
+      loop: !currentOptions.loop
+    }))
+  }
+
+  // ...
+}
+```
+
+</TabsItem>
+<TabsItem tab={TABS_LIBRARY.TABS.SVELTE}>
+
+```html highlight={7-10}
+<script>
+  import emblaCarouselSvelte from 'embla-carousel-svelte'
+
+  let options = { loop: true }
+
+  function toggleLoop() {
+    options = {
+      ...options,
+      loop: !options.loop
+    }
+  }
+</script>
+
+<div class="embla" use:emblaCarouselSvelte="{{ options }}">...</div>
+```
+
+</TabsItem>
+</Tabs>
+
 ### TypeScript
 
 The `EmblaOptionsType` is obtained directly from the **core package** `embla-carousel` and used like so:
diff --git a/packages/embla-carousel-docs/src/content/pages/api/plugins.mdx b/packages/embla-carousel-docs/src/content/pages/api/plugins.mdx
index 9c0a619d..3580e386 100644
--- a/packages/embla-carousel-docs/src/content/pages/api/plugins.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/api/plugins.mdx
@@ -348,13 +348,13 @@ export function EmblaCarousel() {
 
 ```html highlight={9}
 <script setup>
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import emblaCarouselVue from 'embla-carousel-vue'
   import Autoplay from 'embla-carousel-autoplay'
 
   const [emblaRef, emblaApi] = emblaCarouselVue({ loop: true }, [Autoplay()])
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) emblaApi.value.plugins().autoplay.stop()
   })
 
@@ -367,7 +367,7 @@ export function EmblaCarousel() {
 <TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
 
 ```jsx highlight={12}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import createEmblaCarousel from 'embla-carousel-solid'
 import Autoplay from 'embla-carousel-autoplay'
 
@@ -377,7 +377,7 @@ export function EmblaCarousel() {
     () => [AutoPlay()]
   )
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) api.plugins().autoplay.stop()
   })
@@ -464,7 +464,7 @@ export function EmblaCarousel() {
 
 ```html highlight={13}
 <script setup>
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import emblaCarouselVue from 'embla-carousel-vue'
   import Autoplay from 'embla-carousel-autoplay'
 
@@ -474,7 +474,7 @@ export function EmblaCarousel() {
     console.log(`Autoplay just triggered ${eventName}!`)
   }
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) emblaApi.value.on('autoplay:stop', logPluginEvent)
   })
 
@@ -486,7 +486,7 @@ export function EmblaCarousel() {
 <TabsItem tab={TABS_LIBRARY.TABS.SOLID}>
 
 ```jsx highlight={17}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import createEmblaCarousel from 'embla-carousel-solid'
 import Autoplay from 'embla-carousel-autoplay'
 
@@ -500,7 +500,7 @@ export function EmblaCarousel() {
     console.log(`Autoplay just triggered ${eventName}!`)
   }
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) api.on('autoplay:stop', logPluginEvent)
   })
diff --git a/packages/embla-carousel-docs/src/content/pages/get-started/react.mdx b/packages/embla-carousel-docs/src/content/pages/get-started/react.mdx
index deadd088..598d4fb3 100644
--- a/packages/embla-carousel-docs/src/content/pages/get-started/react.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/get-started/react.mdx
@@ -11,6 +11,8 @@ import { TABS_PACKAGE_MANAGER } from 'consts/tabs'
 
 # React
 
+Embla Carousel provides a wrapper for [React](https://react.dev/) that ensures seamless integration of the carousel into your React project and automatic cleanup on component unmount.
+
 Start by installing the Embla Carousel **npm package** and add it to your dependencies.
 
 <Tabs groupId={TABS_PACKAGE_MANAGER.GROUP_ID}>
diff --git a/packages/embla-carousel-docs/src/content/pages/get-started/solid.mdx b/packages/embla-carousel-docs/src/content/pages/get-started/solid.mdx
index c46dd126..f37ec8cc 100644
--- a/packages/embla-carousel-docs/src/content/pages/get-started/solid.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/get-started/solid.mdx
@@ -11,6 +11,8 @@ import { TABS_PACKAGE_MANAGER } from 'consts/tabs'
 
 # Solid
 
+Embla Carousel provides a wrapper for [Solid](https://www.solidjs.com/) that ensures seamless integration of the carousel into your Solid project and automatic cleanup on component unmount.
+
 Start by installing the Embla Carousel **npm package** and add it to your dependencies.
 
 <Tabs groupId={TABS_PACKAGE_MANAGER.GROUP_ID}>
@@ -73,16 +75,16 @@ The method gives us a **ref** to attach to our wrapping element with the classna
 
 ## Accessing the carousel API
 
-The `createEmblaCarousel` method takes the Embla Carousel [options](/api/options/) as the first argument, which is a Solid accessor. Additionally, you can access the [API](/api/) with a `createEffect` like demonstrated below:
+The `createEmblaCarousel` method takes the Embla Carousel [options](/api/options/) as the first argument, which is a Solid accessor. Additionally, you can access the [API](/api/) with a `onMount` like demonstrated below:
 
 ```jsx highlight={5,7-12}
-import { createEffect } from 'solid-js'
+import { onMount } from 'solid-js'
 import createEmblaCarousel from 'embla-carousel-solid'
 
 export function EmblaCarousel() {
   const [emblaRef, emblaApi] = createEmblaCarousel(() => ({ loop: true }))
 
-  createEffect(() => {
+  onMount(() => {
     const api = emblaApi()
     if (api) {
       console.log(api.slideNodes()) // Access API
diff --git a/packages/embla-carousel-docs/src/content/pages/get-started/svelte.mdx b/packages/embla-carousel-docs/src/content/pages/get-started/svelte.mdx
index 6a300d48..1ff06bd7 100644
--- a/packages/embla-carousel-docs/src/content/pages/get-started/svelte.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/get-started/svelte.mdx
@@ -11,6 +11,8 @@ import { TABS_PACKAGE_MANAGER } from 'consts/tabs'
 
 # Svelte
 
+Embla Carousel provides a wrapper for [Svelte](https://svelte.dev/) that ensures seamless integration of the carousel into your Svelte project and automatic cleanup on component unmount.
+
 Start by installing the Embla Carousel **npm package** and add it to your dependencies.
 
 <Tabs groupId={TABS_PACKAGE_MANAGER.GROUP_ID}>
diff --git a/packages/embla-carousel-docs/src/content/pages/get-started/vue.mdx b/packages/embla-carousel-docs/src/content/pages/get-started/vue.mdx
index 4823e23b..4b3748e9 100644
--- a/packages/embla-carousel-docs/src/content/pages/get-started/vue.mdx
+++ b/packages/embla-carousel-docs/src/content/pages/get-started/vue.mdx
@@ -11,6 +11,8 @@ import { TABS_PACKAGE_MANAGER } from 'consts/tabs'
 
 # Vue
 
+Embla Carousel provides a wrapper for [Vue](https://vuejs.org/) that ensures seamless integration of the carousel into your Vue project and automatic cleanup on component unmount.
+
 Start by installing the Embla Carousel **npm package** and add it to your dependencies.
 
 <Tabs groupId={TABS_PACKAGE_MANAGER.GROUP_ID}>
@@ -31,9 +33,11 @@ Start by installing the Embla Carousel **npm package** and add it to your depend
 </Tabs>
 
 <Admonition type="note">
-**Note:** `embla-carousel-vue` only supports `Vue 3` and up.
-However, you can use the [vanilla version](/module/) and re-create the behaviour of `embla-carousel-vue`.
-[Here's an example](https://github.com/meirroth/embla-carousel-vue2) of how you can use Embla Carousel with `Vue 2` Options API.
+  **Note:** `embla-carousel-vue` only supports `Vue 3` and up. However, you can
+  use the [core package](/get-started/module/) that `embla-carousel-vue` is
+  using under the hood, and re-create the behaviour of `embla-carousel-vue`.
+  Here's an [example](https://github.com/meirroth/embla-carousel-vue2) of how
+  you can use Embla Carousel with `Vue 2` Options API.
 </Admonition>
 
 ---
@@ -81,16 +85,16 @@ The `emblaCarouselVue` function gives us an **emblaRef** to attach to our wrappi
 
 ## Accessing the carousel API
 
-The `emblaCarouselVue` function takes the Embla Carousel [options](/api/options/) as the first argument. Additionally, you can access the [API](/api/) with an `watchEffect` like demonstrated below:
+The `emblaCarouselVue` function takes the Embla Carousel [options](/api/options/) as the first argument. Additionally, you can access the [API](/api/) with an `onMounted` like demonstrated below:
 
 ```html highlight={5,7-11}
 <script setup>
-  import { watchEffect } from 'vue'
+  import { onMounted } from 'vue'
   import emblaCarouselVue from 'embla-carousel-vue'
 
   const [emblaRef, emblaApi] = emblaCarouselVue({ loop: false })
 
-  watchEffect(() => {
+  onMounted(() => {
     if (emblaApi.value) {
       console.log(emblaApi.value.slideNodes()) // Access API
     }