---
title: Miniapp Card
---
## Miniapp Card development
A widget represents a small part of a miniapp. This topic describes how to develop widgets to achieve the desired display and interaction effect（Currently, only OEM App are supported.）.
To develop widgets in your miniapp project, you can add a directory to store the programming code of widgets, and add a statement to `project.tuya.json`.
### Create a widget project
In Tuya MiniApp IDE, create a project and choose a widget template to start a widget project.
### Configure project
#### Declare widget directory in `project.tuya.json`
```json
{
"projectname": "widget-demo",
"i18n": true,
+ "miniprogramRoot": "app/", ## Source code the miniapp.
+ "widgetRoot": "widget/", ## Source code of the widget.
"baseversion": "2.10.12",
"compileType": "widget",
"dependencies": {
"BaseKit": "3.0.0",
"MiniKit": "3.0.0",
"BizKit": "3.0.1"
}
}
```
> Note: Migrate the miniapp files to the `app` directory.
- The widget directory is added to the miniapp project.
```text
├── package.json
├── project.tuya.json
├── app
│ ├── app.js
│ ├── app.json
│ ├── app.tyss
│ ├── assets
│ ├── i18n
│ ├── components
│ ├── pages
│ │ └── home
│ │ ├── index.json
│ │ ├── index.tyss
│ │ ├── index.tyml
│ │ ├── index.js,ts
│ │ └── index.rjs
│ └── theme.json
├── widget
│ ├── assets
│ ├── cards
│ │ └── weather
│ │ ├── index.json
│ │ ├── index.tyss
│ │ ├── index.tyml
│ │ ├── index.js,ts
│ │ └── index.rjs
└─────└── widget.json
```
#### Describe widget information in `widget.json`
```js
{
widgets: ['pages/home/index', 'pages/list/index'];
}
```
You can declare multiple widgets.
#### Create widget page files
Each widget has a subdirectory configured, so the number of widgets determines the number of subdirectories.
Each widget includes the following four files:
- `[WidgetPath].ts`: registers a widget.
- `[WidgetPath].tyml`: the structure of the widget.
- `[WidgetPath].tyss`: the style of the widget.
- `[WidgetPath].json`: the configuration of the widget.
- `[WidgetPath].rjs`: (optional) the rendering script file of the widget.
```json
widget
├── cards
│ └── home
│ ├── index.json
│ ├── index.tyss
│ ├── index.tyml
│ ├── index.ts
│ └── index.rjs
└── widget.json
```
### Miniapp Card project configuration
- (Required) `size`: The size of the widget. Valid values are `tiny`, `small`, `middle`, `large`, and custom aspect ratio (width relative to page width). Dynamic size is not supported.
- `isDisablePadding`: Whether to display spacing and rounded corner, in Boolean format.
```json
{
"size": "middle",
// "size": "middle"
// "size": "large"
// "size": 0.75
"isDisablePadding": true
}
```
### Miniapp Card component
Different from a miniapp page, a widget supports only a limited number of components for UI design. The following table lists the built-in widgets that are currently supported.
| Name | Features |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [view](/en/miniapp/develop/miniapp/component/view-container/view) | Layout container |
| [button](/en/miniapp/develop/miniapp/component/form-component/button) | Button |
| [text](/en/miniapp/develop/miniapp/component/basic-content/text) | Text |
| [image](/en/miniapp/develop/miniapp/component/media-component/image) | Image container |
| [swiper](/en/miniapp/develop/miniapp/component/view-container/swiper) | Swiper view container |
| [swiper-item](/en/miniapp/develop/miniapp/component/view-container/swiper-item) | Sub-item of swiper view container |
| [canvas](/en/miniapp/develop/miniapp/component/canvas/canvas) | Canvas for drawing charts with [rjs Render Script](/en/miniapp/develop/miniapp/framework/api/render) |
| [movable-area](/en/miniapp/develop/miniapp/component/view-container/movable-area) | The movable area of the `movable-view` component |
| [movable-view](/en/miniapp/develop/miniapp/component/view-container/movable-view) | Movable view container. It can be dragged to move on a page. The `movable-view` component must be included in the `movable-area` component. It must be a direct child node. Otherwise, the component cannot move |
| [switch](/en/miniapp/develop/miniapp/component/form-component/switch) | Switch picker |
| [slider](/en/miniapp/develop/miniapp/component/form-component/slider) | Slider picker |
### Miniapp Card API
The widget API is injected through the Kit. The Kit dependencies must be the same as those used by the miniapp into which the widgets are embedded. Declare the required Kits in `project.tuya.json`, as shown in the following example:
```js
{
"dependencies": {
"BaseKit": "3.0.0",
"MiniKit": "3.0.0",
"BizKit": "3.0.1"
}
}
```
### Miniapp Card registration
`Widget()` is a constructor that defines the initial data, lifecycle callbacks, event handler functions, and other required data of widgets. Each widget must be registered with the [Widget()](/en/miniapp/develop/miniapp/framework/api/widget) function, and it is registered only once.
The registration options for widgets are similar to those for miniapp pages. For more information, see [Widget()](/en/miniapp/develop/miniapp/framework/api/widget).
```js
Widget({
data: { text: 'Initial data'},
onLoad(query){
console.log(query); // You can get the path of the current widget from the onLoad parameters.
}, // Widget loading
onShow(){}, // Triggered when the container is visible.
onReady(options){ // The widget has been initially rendered.
this.setData({ text: "Update data" })
},
onHide(){}, // Triggered when the container is hidden.
onRefresh(){} // Updated when the widget is reloaded. It is typically used for pull-to-refresh in the app.
onPageScroll(){} // Triggered when the widget card is scrolled.
onUnload(){}, // Triggered when the container is unloaded.
onThemeChange(){} // Listen for theme changes.
...
// Other methods.
})
```
Tips:
- The spacing between widgets is set to 12 pixels.
- Each round corner of a widget is set to 16 pixels.
### Miniapp Card dynamic height
- Miniapp Card API `ty.setWidgetHeight`: Adjust the widget height dynamically.
**Object object**
| Property | Type | Default value | Required | Description |
| -------- | ---------- | ------------- | -------- | ----------------------------------------------------------------------------- |
| height | `number` | | Yes | The widget width, in pixels (px). |
| complete | `function` | | No | The completion callback (always executed whether the call succeeds or fails). |
| success | `function` | | No | The success callback. |
| fail | `function` | | No | The fail callback. |
- Miniapp Card method `getWidgetInfo`: Get the size of the widget.
- Miniapp Card method `rpxToPx`: Convert the value from rpx to px, with the parameter of value type.
- Miniapp Card lifecycle `onResize`: Listen for the dynamic change in widget height, with the callback parameter being the current width and height of the widget.
Example
```js
Widget({
data: {},
onResize(query) {
console.log('onResize', query); // query: {height, width} Unit: px
},
changeHeight(e) {
const widgetInfo = this.getWidgetInfo(); // widgetInfo: {height, width} Unit: px
const addHeight = this.rpxToPx(100); // convert rpx to px
const allHeight = widgetInfo.height + addHeight;
ty.setWidgetHeight({
height: allHeight, // Unit of the height: px
success: (res) => {
console.log('Widget height set successfully', res);
},
fail: (err) => {
console.log('Widget height setting failed', err);
}
});
},
})
```
## Platform configuration
Configure the necessary information for your widget on the Tuya MiniApp Developer Platform and IoT Development Platform.
### MiniApp Developer Platform
Open [MiniApp Developer Platform](https://iot.tuya.com/miniapp). Select your miniapp, choose **Basic Settings**, and click **Add Settings** to specify widget information.
### IoT Development Platform
Choose your app on the [Tuya Developer Platform](https://iot.tuya.com/oem/index). Click **Detailed Settings**.
In the **Page** module, choose **Home**, click **Add Card**, and then select your widget.
[Explore more](https://developer.tuya.com/en/docs/iot/smart-life-app-updates?id=Kd4is05osruqn#title-4-OEM%20App%20Customization%20Lite).