---
name: "useDevicesProps"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.16.0" }
title: "useDevicesProps"
---

## useDevicesProps

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

> 💡 Before use, mount SdmDevicesProvider and configure the associated device mapping.
> Performance optimization (best practices):
> 1. Strongly recommend always scoping the selector to the exact feature point, e.g., useDevicesProps(props => props.main?.switch_led), to avoid full subscriptions that cause unnecessary rerenders when unrelated devices or feature points change.
> 2. If the selector must return an object containing multiple fields, the default shallow comparison (shallow equal) ensures rerender will not be triggered as long as the extracted values do not change. If needed, pass a custom equalityFn.

### Description

Get the DP state set of associated devices.

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `selector` | `(devicesProps: { [key: string]: DpState }) => DpValue;` | Yes | Selector function. The input is the props aggregation object for all associated devices. Keys are device identifiers, and values are the device’s DP key–value pairs |
| `equalityFn` | `(prev: DpValue, next: DpValue) => boolean;` | No | Custom comparison function; if it returns true, re-render is not triggered; default is shallow equal |

### Return Value

Type: `DpValue`

DP values selected by the selector; type is inferred from the selector’s return value

**`type` DpValue**

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

### Referenced Types

##### `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>;
```

##### `type` DpValue

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

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


### Examples

#### Subscribe only to a specific state of a single device

```tsx
import { useDevicesProps } from '@ray-js/panel-sdk';

export default function Lamp1Switch() {
  // Re-render only when lamp1's switch_led changes
  const switchLed = useDevicesProps(p => p?.lamp1?.switch_led);

  return <Text>lamp1 switch: {switchLed ? 'ON' : 'OFF'}</Text>;
}
```

#### Custom rerender

```tsx
// useDevicesProps has built-in shallow equality checks on the selector's return value; in typical cases, you don't need to pass equalityFn.
import { useDevicesProps } from '@ray-js/panel-sdk';

export default function PowerMap() {
  const powerMap = useDevicesProps(
    p => {
      const map: Record<string, boolean> = {};
      Object.keys(p ?? {}).forEach(k => { map[k] = !!p[k]?.switch_led; });
      return map;
    },
    (prev, next) => JSON.stringify(prev) === JSON.stringify(next)
  );

  return (
    <View>
      {Object.keys(powerMap).map(k => (
        <Text key={k}>{k}: {powerMap[k] ? 'ON' : 'OFF'}</Text>
      ))}
    </View>
  );
}
```