[docs] Carousel `to` API incorrect (v4)

[mryellow]

Prerequisites

• I have searched for duplicate or closed issues
• I have validated any HTML to avoid common problems
• I have read the contributing guidelines

Describe the issue

.carousel('to')
Cycles the carousel to a particular frame (0 based, similar to an array). Returns to the caller before the next item has been shown (i.e. before the slid.bs.carousel event occurs).

https://getbootstrap.com/docs/4.6/components/carousel/#carouselto

It's difficult to determine what is meant by this. Probably one of the more obvious assumptions might be that the API is .carousel('to', 0).

Then this page shows (incorrect) examples:

$('#myCarousel').carousel('1')

https://getbootstrap.com/docs/4.6/getting-started/javascript/#asynchronous-functions-and-transitions

This will result in unknown method errors.

...

Instead the undocumented approach of $('#myCarousel').carousel(1) must be used. Somehow Google search AI summary knew about this.

When recognising a number being passed it will jump to that frame.

Reduced test cases

$('#myCarousel').carousel('to', 1)

$('#myCarousel').carousel('1')

What operating system(s) are you seeing the problem on?

Linux

What browser(s) are you seeing the problem on?

Chrome

What version of Bootstrap are you using?

4.6 website documentation

[julien-deramond]

Thanks for the feedback, @mryellow!

Unfortunately, Bootstrap 4 is now end-of-life (EOL), so we won’t be updating its documentation. Since the structure of the Bootstrap 5 docs is quite different, this issue doesn’t apply directly there.

I’ll go ahead and close this issue for now. But feel free to comment if you believe there’s still something worth addressing in the v5 documentation. :)

[mryellow]

The docs are not EOL. They're live on your site right this very second.... and incorrect.

[mryellow]

While yes. The docs are still wrong in v5.

bootstrap/js/src/carousel.js

Lines 169 to 188 in 3b9a416

	to(index) {
	const items = this._getItems()
	if (index > items.length - 1 || index < 0) {
	return
	}
	if (this._isSliding) {
	EventHandler.one(this._element, EVENT_SLID, () => this.to(index))
	return
	}
	const activeIndex = this._getItemIndex(this._getActive())
	if (activeIndex === index) {
	return
	}
	const order = index > activeIndex ? ORDER_NEXT : ORDER_PREV
	this._slide(order, items[index])
	}

to(index) does not validate for type but then immediately does:

if (index > items.length - 1 || index < 0) {

Indicating that a Number is expected.

Your docs for v5 still indicate that a string should be passed.

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

carousel.to('1') // Will start sliding to the slide 1 and returns to the caller
carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!

https://getbootstrap.com/docs/5.3/getting-started/javascript/#asynchronous-functions-and-transitions

While you're fixing your v5 docs perhaps you could take a moment to fix the same errors in your currently published and very much still live v4 docs.

[mryellow]

p.s. Where are the Javascript API docs? These look like just examples rather than real API docs.

We see things like getInstance described via examples but nowhere is the signature of this method clearly documented. Same for all the other methods.

This lack of a real API doc might be the reason why you're passing wrong args in your examples and confusing yourself when writing these docs.

[julien-deramond]

The docs are not EOL. They're live on your site right this very second.... and incorrect.

Version 4 has reached end-of-life (EOL) as of 2023. Its documentation will no longer be updated, and no new v4 releases are planned.

We appreciate your feedback on version 5 and will review your comments, thank you!