diff --git a/docs/components/carousel/index.md b/docs/components/carousel/index.md
new file mode 100644
index 0000000000..ba95201aa9
--- /dev/null
+++ b/docs/components/carousel/index.md
@@ -0,0 +1,3 @@
+# Carousel ||10
+
+-> go to Overview
diff --git a/docs/components/carousel/overview.md b/docs/components/carousel/overview.md
new file mode 100644
index 0000000000..c80859af4c
--- /dev/null
+++ b/docs/components/carousel/overview.md
@@ -0,0 +1,39 @@
+# Carousel >> Overview ||10
+
+A carousel web component. The component allows users to navigate through a series of images using either UI controls or keyboard navigation.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-carousel.js';
+```
+
+```js preview-story
+export const main = () =>
+ html`
+
+
+
+
+
+
+
+ `;
+```
+
+## Features
+
+- Flexible Content and Styling: LionCarousel accepts diverse content through `slot=slide` and offers styling options.
+- Autoplay and Manual Navigation: It supports both automatic cycling of slides for showcases and manual navigation for user control.
+- Accessibility-Focused: Built with accessibility in mind, featuring keyboard navigation, ARIA attributes, and motion preferences.
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionCarousel } from '@lion/ui/carousel.js';
+// or
+import '@lion/ui/define/lion-carousel.js';
+```
diff --git a/docs/components/carousel/use-cases.md b/docs/components/carousel/use-cases.md
new file mode 100644
index 0000000000..0ee1979796
--- /dev/null
+++ b/docs/components/carousel/use-cases.md
@@ -0,0 +1,59 @@
+# Carousel >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-carousel.js';
+```
+
+## Pre-select the first active slide
+
+You can preselect the active slide using the `current` attribute.
+
+```html preview-story
+
+
slide 1
+
slide 2
+
slide 3
+
Any HTML content
+
More content here
+
+```
+
+## Autoplay Carousel
+
+You can define an autoplay carousel using the `slideshow` atribute and set the delay duration using the `duration` attribute, also adds the "play" and "stop" buttons for users to control it.
+
+```html preview-story
+
+
slide 1
+
slide 2
+
slide 3
+
Any HTML content
+
More content here
+
+```
+
+## Carousel with Pagination
+
+You can compose the carousel component to work with LionPagination component
+
+```html preview-story
+
+
+
+ `);
+ expect(el.slides.length).to.equal(2);
+ });
+
+ it('updates active slide on _nextSlide call', async () => {
+ const el = await fixture(html`
+
+
Slide 1
+
Slide 2
+
+ `);
+ el.nextSlide();
+ await el.updateComplete;
+ expect(el.currentIndex).to.equal(2);
+ });
+
+ it('loops to the first slide from the last on _nextSlide call', async () => {
+ const el = await fixture(html`
+
+
Slide 1
+
Slide 2
+
+ `);
+ el.currentIndex = 2;
+ el.nextSlide();
+ await el.updateComplete;
+ expect(el.currentIndex).to.equal(1); // Loops back to the first slide
+ });
+
+ it('should start slideshow when slideShow is passed', async () => {
+ const el = await fixture(html``);
+ expect(el.slideshow).to.be.true;
+ expect(el.slideShowTimer).to.exist;
+ // @ts-ignore
+ el._stopSlideShow(); // Clean up to prevent the timer from running
+ });
+});
+
+describe('LionCarousel Accessibility', () => {
+ it('passes accessibility tests', async () => {
+ const el = await fixture(html`
+
+