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

# messagebox

Opens a Windows message-box popup and returns the code of the button the user clicked.

```luau theme={null}
messagebox(text: string, caption: string, flags: number): number
```

`text` is the popup body, `caption` is the title bar, and `flags` is a number that packs three things at once: the button set in the low 4 bits, an icon, and which button starts selected. The value passes straight to Win32's `MessageBoxA`, so the codes below come from Microsoft's docs.

Most commonly used to ask the user to confirm before a script does something they can't undo.

<Warning>
  Calling `messagebox` freezes the entire Roblox client until the user dismisses the popup. Visuals don't redraw, input doesn't register, and no Luau coroutine runs while it's open.
</Warning>

**Common button styles** (low 4 bits, mutually exclusive):

* `0` - MB\_OK: just OK
* `1` - MB\_OKCANCEL: OK and Cancel
* `3` - MB\_YESNOCANCEL: Yes, No, and Cancel
* `4` - MB\_YESNO: Yes and No

**Icon bits** (added to the button style for a coloured icon next to the text):

* `0x10` - red error
* `0x20` - question mark (deprecated by Microsoft but still works)
* `0x30` - yellow warning triangle
* `0x40` - blue info (i)

`flags = 4 + 0x30` opens a Yes/No popup with the warning icon. Default-button selectors (`0x100`, `0x200`, `0x300`) and rarer button sets (Abort/Retry/Ignore, Cancel/TryAgain/Continue) live in the Microsoft docs. <br /> [Learn more here.](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-messagebox)

## Parameters

| Parameter | Type     | Description                                                      |
| --------- | -------- | ---------------------------------------------------------------- |
| `text`    | `string` | Body text shown inside the popup.                                |
| `caption` | `string` | Title bar text.                                                  |
| `flags`   | `number` | Bitfield - button style, optional icon, optional default-button. |

## Returns

`number` - the Win32 ID constant for the button the user clicked:

| Value | Constant | Triggered by |
| ----- | -------- | ------------ |
| `1`   | IDOK     | OK           |
| `2`   | IDCANCEL | Cancel       |
| `6`   | IDYES    | Yes          |
| `7`   | IDNO     | No           |

## Example

<CodeGroup>
  ```luau Example 1 theme={null}
  <<<<<<< HEAD
  local choice = messagebox("Click OK to continue", "Alert", 0)
  =======
  -- messagebox(text: string, caption: string, flags: number): number
  >>>>>>> 50e30f53759b0538759af25c9b271514aa2c9290
  ```

  ```luau Example 2 theme={null}
  -- Prompt before the script does anything
  local agree = messagebox(
      "This script does this and that.\nClick OK to accept the risk.",
      "Warning",
      1 + 0x30 -- MB_OKCANCEL + warning icon
  )

  if agree ~= 1 then -- IDOK
      return -- user declined
  end

  -- Check if the script executed in the right game
  if game.PlaceId ~= 123456789 then 
      messagebox(
          "This script only works in [target game].\nJoin the right game and re-execute.",
          "Wrong game",
          0 + 0x10 -- MB_OK + error icon
      )

      return
  end

  -- Save before resetting settings
  local choice = messagebox(
      "Save the current settings before resetting?",
      "Script title",
      3 + 0x20 -- MB_YESNOCANCEL + question icon
  )

  if choice == 6 then -- IDYES
      saveSettings()
      reset()
  elseif choice == 7 then -- IDNO
      reset()
  end

  -- IDCANCEL (2) leaves both branches untaken
  ```
</CodeGroup>

<Tip>
  Calling `messagebox` freezes the entire Roblox client until the user dismisses the popup. Visuals don't redraw, input doesn't register, and no Luau coroutine runs while it's open.
</Tip>