Skip to main content

WMX component schema

Each WMX component has UI code in index.tsx, metadata in wmx.json, and an optional icon. For an overview, see WMX components.

How a WMX component connects to the app

Component structure​

ComponentName/
├── index.tsx
├── wmx.json
└── icon.svg (optional)
FilePurpose
index.tsxThe component and its logic
wmx.jsonDefines properties, events and styles
icon.svgOptional Studio icon

The folder name, the name in wmx.json, and the componentname used in page markup must be the same.

wmx.json overview​

props, events and styles are maps. The key is the name Studio and the app use, and the value is the schema entry.

{
"name": "Carousel",
"displayName": "Carousel",
"description": "Image carousel",
"webSupport": true,
"iconUrl": "icon.svg",
"props": {},
"events": {},
"styles": {}
}

Metadata fields​

FieldDescriptionRequiredDefault
nameUnique component identifier. Matches the folder name.Yesnone
displayNameLabel shown in StudioNoname
descriptionHelp textNonone
iconUrlRelative path to the icon, for example icon.svgNonone
webSupportSet to true for web appsNofalse
propsMap of propertiesNonone
eventsMap of eventsNonone
stylesMap of style slotsNonone

Property schema​

FieldDescriptionRequiredDefault
nameProperty identifier. Matches the map key.Yesnone
displayNameLabel in StudioNoname
descriptionHelp textNonone
typestring, number, boolean, object or arrayNostring
defaultValueInitial value when the widget is placed on a pageNonone
"props": {
"dataset": { "name": "dataset", "type": "array", "defaultValue": [] },
"autoplay": { "name": "autoplay", "type": "boolean", "defaultValue": true }
}

Each property you declare is passed to your component as a prop with the same name, and can be bound to a variable in Studio.

Event schema​

FieldDescriptionRequiredDefault
nameEvent identifier. Matches the key.Yesnone
displayNameLabel in the Events tabNoname
descriptionHelp text, and what the event passesNonone
"events": {
"onSlideChange": {
"name": "onSlideChange",
"displayName": "On Slide Change",
"description": "Triggered when the slide changes. Receives the new index."
}
}

Your component calls the event as a function prop, for example onSlideChange?.(index). The handler you attach on the page runs.

Style schema​

FieldDescriptionRequiredDefault
nameStyle slot identifier. Matches the key.Yesnone
displayNameLabel in the Properties panelNoname
styleDefault CSS style object for the slotNonone
"styles": {
"root": { "name": "root", "style": { "borderRadius": "8px" } },
"caption": { "name": "caption", "style": { "fontSize": "14px" } }
}

Style values are CSS. Your component receives a styles prop with one entry per slot, shaped like { root: { style: {...} } }.

Properties WaveMaker provides​

You do not declare these in wmx.json. Your component receives them:

PropWhat it is
nameThe widget name on the page
stylesThe style slots from wmx.json, with any changes made in Studio
classnameThe class set on the widget. Put it on the outermost element.
disabledWhether the widget is disabled
listenerLets the component update its own properties in the app. See Update a property from the component.

show is handled for you. When it is false, WaveMaker hides the component.

In a form field, the component also receives the field's settings, such as datavalue (the field value), readonly and required, when you declare them in wmx.json.

Do not declare show, name, disabled, classname, styles or showindevice in wmx.json.

index.tsx overview​

import React from "react";

const MyComponent = ({ title = "Hello", classname = "", styles }) => (
<div className={classname} style={styles?.root?.style}>
{title}
</div>
);

export default MyComponent;
  • Export the component as the default export.
  • Accept props that match props and events in wmx.json.
  • Apply classname and the root style to the outermost element.

Update a property from the component​

When the component itself changes a property, such as the selected value of an input or the current slide of a carousel, tell the app:

listener?.onChange?.(name, { currentIndex: 2 });

The second argument holds the property names and their new values. After this call, bindings to currentIndex update, and page scripts read the new value from Page.Widgets.<name>.currentIndex. This is how built-in widgets report their own changes.

icon.svg guidelines​

  • SVG format only
  • Transparent background
  • Stroke color #737373

Summary​

wmx.json describes what Studio shows. index.tsx is your React code. The props above connect the two.