diff --git a/components.json b/components.json
index 959dfd86f..ae845177e 100644
--- a/components.json
+++ b/components.json
@@ -54,5 +54,6 @@
"rate": "./packages/rate/index.js",
"steps": "./packages/steps/index.js",
"step": "./packages/step/index.js",
- "carousel": "./packages/carousel/index.js"
+ "carousel": "./packages/carousel/index.js",
+ "carousel-item": "./packages/carousel-item/index.js"
}
diff --git a/examples/docs/en-US/carousel.md b/examples/docs/en-US/carousel.md
index c3ae9fd53..433d7a8f5 100644
--- a/examples/docs/en-US/carousel.md
+++ b/examples/docs/en-US/carousel.md
@@ -1 +1,111 @@
-## carousel
+
+## Carousel
+
+Loop a series of images or texts in a limited space
+
+### Basic usage
+
+::: demo Combine `el-carousel` with `el-carousel-item`, and you'll get a carousel. Content of each slide is completely customizable, and you just need to place it inside `el-carousel-item` tag. By default the carousel switches when mouse hovers over an indicator. Set `trigger` to `click`, and the carousel switches only when an indicator is clicked.
+```html
+
+
+ Switch when indicator is hovered (default)
+
+
+
{{ item }}
+
+
+
+
+ Switch when indicator is clicked
+
+
+
{{ item }}
+
+
+
+
+```
+:::
+
+### Indicators
+
+Indicators can be displayed outside the carousel
+
+::: demo The `indicator-position` attribute determines where the indicators are located. By default they are inside the carousel, and setting `indicator-position` to `out` moves them outside.
+```html
+
+
+
+
{{ item }}
+
+
+
+```
+:::
+
+### Arrows
+
+You can define when arrows are displayed
+
+::: demo The `show-arrow` attribute determines when arrows are displayed. By default they appear when mouse hovers over the carousel. Setting `show-arrow` to `always` or `never` shows/hides the arrows permanently.
+```html
+
+
+
+
{{ item }}
+
+
+
+```
+:::
+
+### Card mode
+
+When a page is wide enough but has limited height, you can activate card mode for carousels
+
+::: demo Setting `card` to `true` activates the card mode. Apart from the appearance, the biggest difference between card mode and common mode is that clicking the slides at both sides directly switches the carousel in card mode.
+```html
+
+
+
+
{{ item }}
+
+
+
+```
+:::
+
+### Attributes
+| Attribute | Description | Type | Accepted Values | Default |
+|---------- |-------------- |---------- |-------------------------------- |-------- |
+| height | height of the carousel | number | — | 300 |
+| initial-index | index of the initially active slide (starting from 0) | number | — | 0 |
+| trigger | how indicators are triggered | string | click | — |
+| arrow-size | size of the arrows | number | — | 36 |
+| interval | interval of the auto loop, in milliseconds. If less than or equal to 0, the carousel will not loop | number | — | 3000 |
+| indicator-position | position of the indicators | string | out | — |
+| show-indicator | whether indicators are shown | boolean | — | true |
+| show-arrow | when arrows are shown | string | always/never | — |
+| card | whether card mode is activated | boolean | — | false |
+
+### Events
+| Event Name | Description | Parameters |
+|---------|---------|---------|
+| index-change | triggers when the active slide switches | index of the new active slide, index of the old active slide |
+
+### Methods
+| Method | Description | Parameters |
+|---------- |-------------- | - |
+| setActiveIndex | manually switch slide | index of the slide to be switched to, starting from 0 |
diff --git a/examples/docs/en-US/form.md b/examples/docs/en-US/form.md
index 834cf7193..750f13463 100644
--- a/examples/docs/en-US/form.md
+++ b/examples/docs/en-US/form.md
@@ -809,10 +809,10 @@ Form component allows you to verify your data, helping you find and correct erro
### Form Methods
-| Method | Description |
-| ---- | ---- |
-| validate(cb) | the method to validate the whole form |
-| validateField(prop, cb) | the method to validate a certain form item |
+| Method | Description | Parameters
+| ---- | ---- | ----
+| validate | the method to validate the whole form | Function(callback: Function(boolean))
+| validateField | the method to validate a certain form item | Function(prop: string, callback: Function(errorMessage: string))
| resetFields | reset all the fields and remove validation result |
### Form-Item Attributes
diff --git a/examples/docs/en-US/table.md b/examples/docs/en-US/table.md
index 2d9150f55..a7440a927 100644
--- a/examples/docs/en-US/table.md
+++ b/examples/docs/en-US/table.md
@@ -1381,7 +1381,7 @@ Customize table column so it can be integrated with other components.
| current-change | triggers when current row changes | currentRow, oldCurrentRow |
### Table Methods
-| Method | Description | Parameter |
+| Method | Description | Parameters |
|------|--------|-------|
| clearSelection | clear selection, might be useful when `reserve-selection` is on | selection |
| toggleRowSelection | toggle if a certain row is selected. With the second parameter, you can directly set if this row is selected | row, selected |
diff --git a/examples/docs/zh-CN/carousel.md b/examples/docs/zh-CN/carousel.md
index b75a3f816..b572d953a 100644
--- a/examples/docs/zh-CN/carousel.md
+++ b/examples/docs/zh-CN/carousel.md
@@ -1 +1,161 @@
-## 走马灯
+
+
+## Carousel 走马灯
+
+在有限空间内，循环播放同一类型的图片、文字等内容
+
+### 基础用法
+
+适用广泛的基础用法
+
+::: demo 结合使用`el-carousel`和`el-carousel-item`标签就得到了一个走马灯。幻灯片的内容是任意的，需要放在`el-carousel-item`标签中。默认情况下，在鼠标 hover 底部的切换条时就会触发切换。通过设置`trigger`属性为`click`，可以达到点击触发的效果。
+```html
+
+