---
name: "useActions"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.2.0" }
title: "useActions - Implemented based on model.actions of the sdm instance"
summary: "useActions is a React Hook provided by @ray-js/panel-sdk, implemented based on model.actions of the sdm instance. Calling it without arguments returns an actions object where each DP provides set and toggle dispatch methods (e.g. actions.switch_1.toggle()). It supports both single devices and groups, and is commonly used together with useProps to read DP state and send commands."
questions:
  - "How to publish a DP? How to publish non-raw type DPs? How to publish non-structured complex type DPs? How to publish DPs in the sdm model?"
  - "How does the actions object returned by useActions toggle a switch DP via actions.switch_1.toggle()?"
  - "useActions is implemented based on model.actions of the sdm instance. What methods does each DP on the actions object provide (e.g. set, toggle)?"
  - "useActions takes no arguments. How is the return type GetSmartDeviceModelActions derived from DpSchema?"
  - "useActions supports both single devices and groups. Will a toggle operation be sent to all sub-devices in a group environment?"
  - "How to use useProps and useActions together to read DP state and send commands?"
  - "What is the difference between useActions and useStructuredActions (basic DP dispatch vs structured complex type dispatch)?"
  - "SdmProvider must be mounted before using useActions. How to quickly integrate via the public-sdm template project?"
  - "What DP operation methods are included in the DpAction type of useActions?"
  - "What is the difference between actions.switch_1.set(true) and actions.switch_1.toggle()?"
  - "How to listen for DP state changes via useProps to update UI after useActions dispatches a command?"
---

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Device Support</span>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Group Support</span>
</div>

## useActions

> [VERSION] @ray-js/panel-sdk >= 1.2.0

> 💡 Implemented on top of the sdm instance. Must be used inside SdmProvider.
> Before using, make sure the project has mounted SdmProvider. For integration, see [Smart Device Model - Usage](/cn/miniapp/solution-panel/ability/common/sdm/usage). For new projects, you can develop directly based on the [public-sdm](https://github.com/Tuya-Community/tuya-ray-materials/tree/main/template/PublicSdmTemplate) example project.

### Description

Get the action method set for smart device capability points. Provides set, toggle, etc. based on the capability type. Commonly used with useProps: useProps reads state, useActions sends commands.

### Parameters

None


### Return Value

Type: `Record<DpCode, DpActions>`

Capability action collection keyed by capability code,
  Each capability exposes different operations by type:
  - All types: set(value) to send directly
  - bool type: on() / off() / toggle() for quick switching
  - value type: inc(step?) / dec(step?) to increment/decrement

### Referenced Types

##### `interface` DpActions

| Property | Type | Description |
| --- | --- | --- |
| `set` | `(value: boolean \| number \| string, options: SendDpOption) => Promise<boolean>` | All types expose this method to send a DP point, but the value you pass depends on the DP type |
| `on` | `1. (options: SendDpOption) => Promise<boolean><br>2. (idx: number, options: SendDpOption) => Promise<boolean>` | Only bool and bitmap types have this method; enable the DP or set the specified bit |
| `off` | `1. (options: SendDpOption) => Promise<boolean><br>2. (idx: number, options: SendDpOption) => Promise<boolean>` | Only bool and bitmap types have this method; disable the DP or clear the specified bit |
| `toggle` | `1. (options: SendDpOption) => Promise<boolean><br>2. (idx: number, options: SendDpOption) => Promise<boolean>` | Available only for bool and bitmap types; toggle the datapoint or flip the specified bit |
| `inc` | `(step: number, options: SendDpOption) => Promise<boolean>` | Available only for the value type; increment by the datapoint's step |
| `dec` | `(step: number, options: SendDpOption) => Promise<boolean>` | Available only for value type; decrease by the current DP step (step) |
| `prev` | `(options: SendDpOption) => Promise<boolean>` | Available only for enum type; switch to the previous enum value |
| `next` | `(options: SendDpOption) => Promise<boolean>` | Available only for enum type; switch to the next enum value |
| `random` | `(options: SendDpOption) => Promise<boolean>` | Available only for enum type; switch to a random enum value |

##### `type` IgnoreDpChangeInterceptorOptions

Configuration option to ignore the DP data change interceptor

Used to configure the debounce mechanism for DP reporting events on the device panel, preventing immediate responses after panel operations from affecting user experience or business logic

| Property | Type | Description |
| --- | --- | --- |
| `whiteDpCodes` | `string[]` | DP whitelist; reports will not be ignored |
| `timeout` | `number` | Debounce timeout check, in milliseconds, default 5000 - The maximum time between sending a DP from the panel and receiving the DP reply; dpDataChange is triggered only if this is exceeded. - Used to debounce DP reporting events |
| `customRule` | `(dpState: DpState, lastSendTimestamp: number) => boolean` | Custom ignore rules > Highest priority; when configured, whiteDpCodes and timeout become ineffective |

##### `type` DevPropInterceptorOptions

| Property | Type | Description |
| --- | --- | --- |
| `blackDpCodes` | `string[]` | DP blacklist; will not be synchronized to the cloud |
| `defaultState` | `DpState` | Default device state on first entry; supports async initialization |
| `throttle` | `number` | Send throttling, in milliseconds, defaults to 0 If set to 0, throttling is disabled. |

##### `type` CustomRawDpMap

Custom DP protocol converter for transforming between raw DP strings and structured objects.
Suitable for composite DPs of type raw/string (e.g., a light's colour_data "00ff003e8"),
splitting a single string into multiple semantic fields (e.g., { hue, saturation, value }).

| Property | Type | Description |
| --- | --- | --- |
| `parser` | `(dpValue: string) => any` | Parse the raw DP string reported by the device into a structured object |
| `formatter` | `(parsedDpValue: any) => string` | Serialize the structured object into a DP string to be sent to the device |

##### `type` DpValue

Datapoint value type, which can be boolean, number, or string.

```typescript
export type DpValue = boolean | number | string;
```

##### `type` SendDpOption

DP send options. Can be used as the global default configuration for createDpKit, and can also be overridden in a single publishDps/action call.
The global `sendDpOption` suits product-level defaults;
options passed for a single send are suitable for temporarily overriding throttling, debouncing, protocol parsing, or optimistic update strategies.
Note: requires the dp-kit interceptor.

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `immediate` | `boolean` | - | Whether to trigger a state update immediately; requires the dp-kit interceptor |
| `ignoreDpDataResponse` | `boolean \| IgnoreDpChangeInterceptorOptions` | `1.11.0` | Whether to ignore DP reports; default false |
| `synchronizeDevProperty` | `boolean \| DevPropInterceptorOptions` | `1.11.0` | Whether to sync dpData with cloud device properties; default false |
| `ordered` | `boolean` | - | Whether to send multiple DPs in the order of the object’s keys; requires the dp-kit interceptor; default false |
| `checkRepeat` | `boolean` | - | Whether to check for duplicate values and skip sending; requires the dp-kit interceptor; default false Compared with the current `dpState`; duplicates are detected and not sent |
| `delay` | `number` | - | Delayed send; requires the dp-kit interceptor; default 0, in ms |
| `throttle` | `number` | - | Send throttling (conflicts with debounce); requires the dp-kit interceptor; default 0, in ms |
| `debounce` | `number` | - | Send debounce (conflicts with throttle); requires the dp-kit interceptor; default 0, in ms |
| `protocols` | `Record<string, CustomRawDpMap>` | - | A per-call DP protocol converter; requires the dp-kit interceptor. The key is the dpCode and the value is a `{ parser, formatter }` object: - parser(dpValue: string) => any — parses the raw DP string into a structured object - formatter(parsedValue: any) => string — serializes the structured object into a DP string Affects only this invocation and does not override the global protocols configuration in createDpKit |

##### `type` DpState

Datapoint status object, where the key is the datapoint code and the value is the datapoint value.

```typescript
export type DpState = Record<string, DpValue>;
```

##### `interface` DpSchema

| Property | Type | Description |
| --- | --- | --- |
| `attr` | `number` | DP attribute flag bit, used to mark additional capabilities of the DP |
| `canTrigger` | `boolean` | Whether it can be used as an automation trigger condition |
| `code` | `string` | DP code, e.g., switch |
| `defaultRecommend` | `boolean` | Whether it is the default recommended DP |
| `editPermission` | `boolean` | Whether it has edit permission |
| `executable` | `boolean` | Whether it can be issued (sent downstream) |
| `extContent` | `string` | DP extension content, typically a JSON string |
| `iconname` | `string` | DP icon name |
| `id` | `string \| number` | DP ID |
| `mode` | `"rw" \| "ro" \| "wr"` | DP mode type rw: writable and reportable (read/write) ro: report-only (read-only) wr: write-only |
| `name` | `string` | DP name, typically used in voice scenarios |
| `property` | `Object` | DP attributes |
| `type` | `"raw" \| "obj"` | DP data type categories: raw for raw byte stream, obj for structured object |

##### `type` DpSchema.property

| Property | Type | Description |
| --- | --- | --- |
| `type` | `"string" \| "bool" \| "value" \| "enum" \| "bitmap" \| "raw"` | DP type |
| `range` | `string[] \| string[]` | Enum value range; present only when type = enum |
| `label` | `string[] \| string[]` | Fault label list; present only when type = bitmap |
| `maxlen` | `number` | Maximum length for fault bitmap; present only when type = bitmap |
| `unit` | `string` | Unit (type = value only) |
| `min` | `number` | Minimum value (type = value only) |
| `max` | `number` | Maximum value (type = value only) |
| `scale` | `number` | Precision (type = value only) |
| `step` | `number` | Step (type = value only) |


### Examples

#### Operation methods for each DP type

```tsx
// devices/schema.ts — 'as const' is the cornerstone of type inference; set is a generic method, others are type-specific shortcuts
import { useProps, useActions } from '@ray-js/panel-sdk';

export const schema = [
  { code: 'switch_led',  property: { type: 'bool' }, type: 'obj', mode: 'rw', id: 1, name: 'Switch' },
  { code: 'brightness',  property: { type: 'value', min: 10, max: 1000, step: 1 }, type: 'obj', mode: 'rw', id: 2, name: 'Brightness' },
  { code: 'work_mode',   property: { type: 'enum', range: ['white', 'colour'] }, type: 'obj', mode: 'rw', id: 3, name: 'Mode' },
  { code: 'fault',       property: { type: 'bitmap', maxlen: 8 }, type: 'obj', mode: 'ro', id: 4, name: 'Fault' },
  { code: 'colour_data', property: { type: 'string', maxlen: 255 }, type: 'obj', mode: 'rw', id: 5, name: 'Color' },
] as const;

function Home() {
  const power = useProps(props => props.switch_led);
  const actions = useActions();

  const handleClick = () => {
    // ✅ set — generic for all types
    actions.switch_led.set(true);            // bool
    actions.brightness.set(500);             // value
    actions.work_mode.set('colour');         // enum (IDE hints 'white' | 'colour')
    actions.fault.set(3);                    // number (bitmap)
    actions.colour_data.set('000003e803e8'); // string

    // bool-specific: on / off / toggle
    actions.switch_led.toggle();
    actions.switch_led.on();
    actions.switch_led.off();

    // value-specific: inc / dec (step by step, automatically clamped to min~max)
    actions.brightness.inc();               // +1 (default step)
    actions.brightness.dec(100);            // -100

    // enum-specific: prev / next / random
    actions.work_mode.next();               // Switch to the next enum value
    actions.work_mode.prev();

    // bitmap-specific: on(idx) / off(idx) / toggle(idx)
    actions.fault.on(0);                    // Set bit 0
    actions.fault.off(1);                   // Clear bit 1
    actions.fault.toggle(2);                // Toggle bit 2
  };

  return (
    <View onClick={handleClick}>
      <Text>Switch: {String(power)}</Text>
    </View>
  );
}
```