---
name: "useBuiltInAlarm"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.8.0" }
title: "useBuiltInAlarm - Implemented based on sdm and alarm-ability"
summary: "useBuiltInAlarm is a React Hook provided by @ray-js/panel-sdk, implemented based on sdm and SmartAlarmAbility. It provides built-in alarm query and toggle capabilities for devices. getBuiltInAlarmList queries the built-in alarm list; setBuiltInAlarmStatus enables/disables alarms in batch via disabled+ruleIds (comma-separated). Returns data (AlarmList[], containing id/name/enabled) and a loading state, and automatically triggers re-renders when the list changes. Only supports single devices, not groups."
questions:
  - "What are the data, loading, getBuiltInAlarmList, and setBuiltInAlarmStatus returned by useBuiltInAlarm?"
  - "getBuiltInAlarmList optionally takes a devId. If not provided, does it query the built-in alarm list of the current device by default?"
  - "In the ISetAlarmSwitch parameter of setBuiltInAlarmStatus, what do disabled and ruleIds represent respectively?"
  - "The ruleIds parameter is a comma-separated string (e.g. 'ruleId1,ruleId2'). Can multiple rules be operated in batch?"
  - "AlarmList type is imported from @ray-js/api/lib/cloud/interface. What are the key fields (id, name, enabled)?"
  - "useBuiltInAlarm only supports single devices, not groups. How should compatibility be handled in a group environment?"
  - "Before using useBuiltInAlarm, you need to mount SdmProvider and integrate SmartAlarmAbility. Where is SmartAlarmAbility configured?"
  - "How to use TyList and TySwitch components to display the built-in alarm list and toggle the disabled state via handleValueChange?"
  - "What is the difference between useBuiltInAlarm and useCustomAlarm (built-in alarm query/toggle vs custom alarm CRUD)?"
  - "What underlying SDM APIs are associated with useBuiltInAlarm (getBuiltInAlarmList, setBuiltInAlarmStatus)?"
---

<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: '#ff4d4f', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Group Not Support</span>
</div>

## useBuiltInAlarm

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

> 💡 Before use, both conditions must be met:
> 1. SdmProvider is mounted in the project
> 2. SmartAlarmAbility is configured when initializing SmartDeviceModel

### Description

Retrieve the built-in alarm list and toggle operations for a device; supports single devices only, groups are not supported.

### Parameters

None


### Return Value

Type: `BuiltInAlarmResult`

Built-in alarm data, loading state, and query/set methods

**`type` BuiltInAlarmResult**

| Property | Type | Description |
| --- | --- | --- |
| `data` | `BuiltInAlarmRule[]` | Built-in alarm list for the device |
| `loading` | `boolean` | Whether the device's built-in alarm list is currently loading |
| `getBuiltInAlarmList` | `(devId: string) => Promise<BuiltInAlarmRule[]>` | Query the built-in alarm list for a device by device ID |
| `setBuiltInAlarmStatus` | `(options: SetBuiltInAlarmStatusParams) => Promise<[boolean, BuiltInAlarmList]>` | Set the built-in alarm list for the device |

### Referenced Types

##### `type` BuiltInAlarmResult

| Property | Type | Description |
| --- | --- | --- |
| `data` | `BuiltInAlarmRule[]` | Built-in alarm list for the device |
| `loading` | `boolean` | Whether the device's built-in alarm list is currently loading |
| `getBuiltInAlarmList` | `(devId: string) => Promise<BuiltInAlarmRule[]>` | Query the built-in alarm list for a device by device ID |
| `setBuiltInAlarmStatus` | `(options: SetBuiltInAlarmStatusParams) => Promise<[boolean, BuiltInAlarmList]>` | Set the built-in alarm list for the device |

##### `type` BuiltInAlarmI18nData

| Property | Type | Description |
| --- | --- | --- |
| `name` | `AlarmLocaleText` | Multilingual name |
| `content` | `AlarmLocaleText` | Multilingual content |

##### `type` BuiltInAlarmRule

| Property | Type | Description |
| --- | --- | --- |
| `auditStatus` | `number` | Review status |
| `boundForPanel` | `boolean` | Whether it is bound to a scene panel |
| `boundForWiFiPanel` | `boolean` | Whether it is bound to a WiFi scene panel |
| `enabled` | `boolean` | Whether enabled |
| `i18nData` | `BuiltInAlarmI18nData` | Multilingual data body |
| `id` | `string` | Rule ID |
| `localLinkage` | `boolean` | Whether it is a local linkage |
| `name` | `string` | Rule name |
| `newLocalScene` | `boolean` | Whether it is an App-controlled local linkage |
| `stickyOnTop` | `boolean` | Whether to display the scene on the home page |

##### `type` BuiltInAlarmList

```typescript
export type BuiltInAlarmList = BuiltInAlarmRule[];
```

##### `type` AlarmLocaleText

| Property | Type | Description |
| --- | --- | --- |
| `en` | `string` | English text |
| `zh` | `string` | Chinese text |


### Examples

#### Example

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

function AlarmPage() {
  const { data, loading, getBuiltInAlarmList, setBuiltInAlarmStatus } = useBuiltInAlarm();

  React.useEffect(() => {
    getBuiltInAlarmList();
  }, []);

  const handleToggle = (item) => (value) => {
    setBuiltInAlarmStatus({ disabled: !value, ruleIds: item.id });
  };

  return data.map(item => (
    <Switch key={item.id} checked={item.enabled} onChange={handleToggle(item)} />
  ));
}
```