> For the complete documentation index, see [llms.txt](https://docs.menanak47.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.menanak47.com/plugins/ak47_lib/interface/text-ui.md).

# Text UI

A lightweight, highly-optimized script for rendering 2D on-screen text and button prompts. Unlike the 3D Text UI, this version is entirely static and event-driven—meaning it has **zero background performance overhead**. It simply acts as a visual prompt and relies completely on your own external scripts to handle the logic, input polling, and distance checks.

**⚙️ Data Structures**

You can configure the 2D Text UI using either a simple string or a full configuration table for advanced control.

**Simple String (Shorthand)** If you just need to display simple text, you can pass a string directly. The system will automatically build the necessary table structure using your default configuration settings.

**The Main Configuration Table**

If you pass a table, this defines *where* the text is positioned on your screen and *what* it displays.

| **Property** | **Type** | **Default**                       | **Description**                                                       |
| ------------ | -------- | --------------------------------- | --------------------------------------------------------------------- |
| position     | `string` | `Config.Defaults.TextUI.position` | The CSS-based screen position (e.g., `'center-left'`, `'top-right'`). |
| options      | `table`  | Required                          | A list of text lines or button prompts (see below).                   |
| scale        | `float`  | `1.0`                             | Scaling factor for the UI element.                                    |

**The Options Table**

Because this script is purely visual, the `options` list only handles display parameters. It does **not** process `action` callbacks, `hold` timers, or `isVisible` checks. You must handle input processing in your own resource loops.

```lua
options = {
    { 
        label = "Access Laptop",    -- The text displayed on screen
        key = 38,                   -- (Optional) The FiveM Control Index (38 is E). Auto-fetches from Lib47.Keys
        keyName = "E",              -- (Optional) Manually override the visual key name displayed inside the box
    },
    { 
        label = "Exit Menu", 
        keyName = "ESC"             -- You can pass a keyName without a control index for pure visuals
    }
}
```

*Supported Positions:* `'top-left'`, `'top-right'`, `'top-center'`, `'bottom-left'`, `'bottom-right'`, `'bottom-center'`, `'center-left'`, `'center-right'`

***

**🛠️ API Reference**

Because 2D Text UI operates natively on the screen rather than in the 3D world, there is only **1 globally active 2D Text UI** allowed at a time per resource. You do not need to manage IDs; firing a new UI will instantly overwrite the previous one.

**1. ShowTextUi**

Renders the 2D Text UI on the screen. It stays visible until you manually hide it or overwrite it.

* Usage: `Lib47.ShowTextUi(data)` (where `data` is a `table` or a `string`)

**2. HideTextUi**

Instantly dismisses the active 2D Text UI.

* Usage: `Lib47.HideTextUi()`

***

**📝 Code Examples**

**Example A: Simple String (Quick Prompt)**

The fastest way to show a prompt. It automatically inherits the `position` from `Config.Defaults.TextUI.position`.

```lua
CreateThread(function()
    -- Show the prompt
    Lib47.ShowTextUi("Press [E] to talk to NPC")
    
    -- Wait for player to press E (You handle the input logic)
    while true do
        Wait(0)
        if IsControlJustReleased(0, 38) then
            print("Talked to NPC!")
            Lib47.HideTextUi() -- Hide it when done
            break
        end
    end
end)
```

**Example B: Advanced Layout**

Use this when you want to customize the position or show multiple keys simultaneously with clean UI button icons.

```lua
RegisterCommand('showui', function()
    Lib47.ShowTextUi({
        position = 'bottom-right',
        scale = 1.1,
        options = {
            { 
                label = "LOCK/UNLOCK", 
                key = 303, -- 'U' key
            },
            { 
                label = "ENGINE", 
                keyName = "G", -- Manual override
            }
        }
    })
end)

RegisterCommand('hideui', function()
    Lib47.HideTextUi()
end)
```

**Example C: Using Exports Directly**

If you do not use the `Lib47` global wrapper, you can use the resource exports directly via the `Interface` wrapper.

```lua
exports['ak47_lib']:ShowTextUi({
    position = 'top-center',
    options = {
        { label = "Entering Restricted Zone..." }
    }
})

-- Later
exports['ak47_lib']:HideTextUi()
```