> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Haptics

> Platform-native haptic feedback system that provides tactile responses for user interactions.

<Note>
  **CLI Setup**: If you create a new Neo project using the [Neo CLI](/cli/commands), NeoHaptics will be automatically initialized for you in `main.dart` through the `NeoInitializer.initialize()` call.
</Note>

## Examples

<Tabs>
  <Tab title="Basic Usage">
    <CodeGroup>
      ```dart Light Feedback lines theme={null}
      await NeoHaptics.light();
      ```

      ```dart Heavy Feedback lines theme={null}
      await NeoHaptics.heavy();
      ```

      ```dart Error Feedback lines theme={null}
      await NeoHaptics.error();
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Button Integration">
    <CodeGroup>
      ```dart With Button Press lines theme={null}
      NeoButton(
        variant: .filled,
        label: "Save Changes",
        onPressed: () async {
          await NeoHaptics.light();
          // Handle save action
        },
      ),
      ```

      ```dart Failed Action lines theme={null}
      NeoButton(
        variant: .filled,
        label: "Upload File",
        onPressed: () async {
          try {
            await NeoHaptics.light();
            await uploadFileToServer(selectedFile);
          } catch (error) {
            await NeoHaptics.error(); // Error feedback
            NeoToast.show(ref, "Upload failed. Please try again.");
          }
        },
      ),
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Form Interactions">
    <CodeGroup>
      ```dart Toggle Switch lines theme={null}
      NeoToggleSwitch(
        isOn: isEnabled.value,
        onChanged: (value) async {
          await NeoHaptics.light();
          isEnabled.value = value;
        },
      ),
      ```

      ```dart Checkbox Selection lines theme={null}
      NeoCheckbox(
        isChecked: isAccepted.value,
        label: "I accept the terms and conditions",
        onChanged: (value) async {
          await NeoHaptics.light();
          isAccepted.value = value;
        },
      ),
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Platform Support

NeoHaptics provides different levels of haptic feedback across platforms:

<Info>
  **iOS**: Full support with Apple Pencil integration and Core Haptics engine for sophisticated tactile patterns.

  **macOS**: Trackpad haptic feedback for built-in MacBook trackpads and Magic Trackpads. By default, haptic feedback is disabled on macOS trackpads to prevent excessive feedback during typical interactions, since trackpads already provide haptic feedback when clicking. You can override this behavior using the `enableMacOS` parameter on individual methods when needed (e.g., for dragging interactions or snapping feedback while already holding down the trackpad).

  **Android**: Fallback to Flutter's built-in haptic feedback system using device vibration motor.

  **Web**: Haptics are not supported and calls are safely ignored.
</Info>

## Methods

### NeoHaptics.initialize()

Initializes the haptic feedback system. **This method is automatically called by `NeoInitializer.initialize()` and typically shouldn't be called manually.**

#### Return Value

<ParamField path="returns" type="Future<void>">
  A Future that completes when the haptic system has been initialized for the current platform.
</ParamField>

### NeoHaptics.light()

Provides subtle haptic feedback, ideal for lightweight interactions like toggles, selections, or confirmations.

#### Optional Parameters

<ParamField path="enableMacOS" type="bool" default="false">
  Whether to enable haptic feedback on macOS trackpads. See [Platform Support](#platform-support) for details about macOS haptic behavior.
</ParamField>

#### Return Value

<ParamField path="returns" type="Future<void>">
  A Future that completes when the haptic feedback has been triggered.
</ParamField>

### NeoHaptics.heavy()

Provides strong haptic feedback for significant interactions like completion of major actions, navigation changes, or important confirmations.

#### Optional Parameters

<ParamField path="enableMacOS" type="bool" default="false">
  Whether to enable haptic feedback on macOS trackpads. See [Platform Support](#platform-support) for details about macOS haptic behavior.
</ParamField>

#### Return Value

<ParamField path="returns" type="Future<void>">
  A Future that completes when the haptic feedback has been triggered.
</ParamField>

### NeoHaptics.error()

Provides distinctive error haptic feedback as a triple-tap pattern with decreasing intensity, perfect for validation errors, failed operations, or warning states.

#### Return Value

<ParamField path="returns" type="Future<void>">
  A Future that completes when the error haptic sequence has been triggered.
</ParamField>

## Best Practices

* **Match Interaction Weight**: Use `light()` for subtle interactions, `heavy()` for significant actions, and `error()` for problems or failures.
* **Avoid Overuse**: Haptic feedback should enhance interactions, not overwhelm them. Not every tap needs haptic feedback.

## Integration Notes

* **Error Handling**: All haptic calls are wrapped in try-catch blocks and failures are logged via [NeoLogger](/utilities/logger) without throwing exceptions.