[Feat]: Improve Vue integration

[1001v]

Which variants of Embla Carousel are relevant to this feature request?

• embla-carousel (Core)
• embla-carousel-react
• embla-carousel-vue
• embla-carousel-svelte
• embla-carousel-autoplay
• embla-carousel-auto-scroll
• embla-carousel-solid
• embla-carousel-auto-height
• embla-carousel-class-names
• embla-carousel-fade
• embla-carousel-docs (Documentation)
• embla-carousel-docs (Generator)

Feature description

Hello. I would like to suggest some improvements for embla-carousel-vue package. I understand, that most of these are breaking, but I believe some of them can be introduced in a future major version.

1. Renaming emblaCarouselVue composable to useEmblaCarousel or just useEmbla. Prefixing composables with 'use' is considered a best practice in vue ecosystem since it marks that the function is a composable, relies on component scope and shall be used respectively. Keeping vue in composable's name also doesn't seem nessesary, since the function itself comes from the package called embla-carousel-vue, so I don't expect much confusion here.
2. Accepting the root ref as an argument instead of returning it from the composable. The current approach limits us to use this composable inside a component only, while it might be needed to use it inside another composable.
3. Returning an object insted of an array from the composable. This will make it order independent to destructure returning object and will make it easier and non-breaking to add more things to return, if there will be.

Example:

<template>
  <div class="embla" ref="emblaRef">
    ...
  </div>
</template>

<script lang="ts" setup>
import useEmbla from 'embla-carousel-vue'

const emblaRef = ref<HTMLDivElement>()
const { emblaApi } = useEmbla(emblaRef, { /* options */ })
</script>

Thanks.

Additional Context

Additional details here...

Before submitting

• I've made research efforts and searched the documentation
• I've searched for existing issues
• I agree to follow this project's Contributing Guidelines for feature requests

[davidjerleke]

Hi @1001v,

Thanks for suggesting improvements. Much appreciated.

1. Renaming emblaCarouselVue composable to useEmblaCarousel or just useEmbla. Prefixing composables with 'use' is considered a best practice in vue ecosystem since it marks that the function is a composable, relies on component scope and shall be used respectively. Keeping vue in composable's name also doesn't seem nessesary, since the function itself comes from the package called embla-carousel-vue, so I don't expect much confusion here.

This can be done without breaking changes because the export is a default export. However, if you or someone else wanting to contribute create a PR for this, I would appreciate if that person search the code for emblaCarouselVue and replace it with useEmblaCarousel. Note that the npm package name should still be embla-carousel-vue.

2. Accepting the root ref as an argument instead of returning it from the composable. The current approach limits us to use this composable inside a component only, while it might be needed to use it inside another composable.

Could you share an example to illustrate his?

3. Returning an object instead of an array from the composable. This will make it order independent to destructure returning object and will make it easier and non-breaking to add more things to return, if there will be.

This depends on the decision we make on point 2. If we decide to keep the current way of doing it, we can leave the array because the first thing you'll always need will be the ref, and optionally the emblaApi. If not, we can discuss the content and shape of the useEmblaCarousel return value.

[1001v]

@davidjerleke Hello! Thanks for the answer.

This can be done without breaking changes because the export is a default export

Yes, but IDE would still suggest to import emblaCarouselVue. So if I understand correctly, renaming is the matter of some contribution.

Could you share an example to illustrate his?

Well, let me try:

import emblaCarouselVue from 'embla-carousel-vue'

// Own composible
// Let's assume we get the ref as an argument
export function useEmbla(wrapper: Ref<HTMLElement>) {
  // Or we might want to inject it from somewhere 
  // const wrapper = inject('wrapper')
  
  // We call embla
  const [emblaRef] = emblaCarouselVue()

  // Now we need to link refs something like that
  watch(wrapper, (value) => {
    if (value) {
      emblaRef.value = value
    }
  })

  // Some other code

 // Some return
}

So, my point is, that the watch part in our own wrapper can be removed completely if emblaCarouselVue gets the ref as an argument in the first place.

This depends on the decision we make on point 2. If we decide to keep the current way of doing it, we can leave the array because the first thing you'll always need will be the ref, and optionally the emblaApi. If not, we can discuss the content and shape of the useEmblaCarousel return value.

I believe that depends on how we see the purpose of the official integration. Should it produce only minimal functionality or should it be a full-featured solution? If it's the second case, then I suppose the composable could return some vue entities which would represent emblaApi's state or even control it.
Example:

// index: Ref<number>
// canScrollNext/canScrollPrev: ComputedRef<boolean> 
const { index, canScrollNext, canScrollPrev } = useEmblaCarousel(wrapperRef)

So the short answer is, that return value should be the object, if farther vuefication of composable is in order.

Thanks.

[davidjerleke]

@1001v thank you for your input.

I believe that depends on how we see the purpose of the official integration. Should it produce only minimal functionality or should it be a full-featured solution?

All library wrappers (embla-carousel-vue, embla-carousel-react, embla-carousel-svelte etc...) are minimal wrappers that just wrap the core embla-carousel package for seamless integration. They basically do the following:

• Take options and plugins as parameters.
• They run emblaApi.reInit() when options or plugins change (deep equality).
• They expose a ref for users attach to the DOM themselves.
• They respect the globalOptions feature.
• They expose the raw emblaApi for maximum flexibility.

For more full-featured, ready-to-use (but heavier) alternatives, you can explore options like shadcn-vue.