> For the complete documentation index, see [llms.txt](https://nexeum.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nexeum.gitbook.io/docs/nex-hud/custom-elements.md).

# Custom Elements

This feature allows you to create custom, updateable, elements inside the existing HUD interface. 

{% stepper %}
{% step %}

### Create Element in Shared Config

You must first create the custom element in the `shared_config.lua` file. This is under `Config.CustomElements`. In the default shared config you'll see two examples of custom elements, one for displaying Duty Unit Counts and one for Staff Members showing the server player count and report statistics. 

| Option             | Description                                                                                                                                                                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Enabled`          | This is the master toggle for whether this element is enabled or not.                                                                                                                                                                                                      |
| `Name`             | This is the name of the custom element, used and displayed in the `/ui` settings menu.                                                                                                                                                                                     |
| `Description`      | This is the description of the custom element, used and displayed in the `/ui` settings menu.                                                                                                                                                                              |
| `Restricted`       | This controls whether this custom element is restricted to certain players or not. If `true`, only players with a later specified ace permission will have the custom element shown on their interface. This is good if you want to restrict the element to staff members. |
| `AcePermission`    | If you choose to restrict the custom element to certain players, this is the ace permission that the custom element will be restricted to. We suggest the following format: `nex-hud.custom_element.<id>`                                                                  |
| `Position`         | This controls where the custom element will be displayed in the main cluster. `1` would be shown at the top, `2` would be shown in second place etc.                                                                                                                       |
| `DefaultState`     | This controls whether the custom element is shown by default, or whether players will have to enable the display of the element in the `/ui` settings menu.                                                                                                                |
| `CanDisable`       | This controls whether players can or cannot disable the view of the custom element in the `/ui` settings menu.                                                                                                                                                             |
| `DefaultInnerHTML` | This is the HTML code that'll be displayed inside the custom element. We suggest you keep this minimal to keep inline with the minimal design of the interface, but it's up to you.                                                                                        |

{% endstep %}

{% step %}

### Set up Custom Elements file

In the main directory of the script contains a <mark style="color:green;">`custom_elements.lua`</mark> file. This is a server-sided file that'll contain the logic for your custom elements. In order to set these up, this will require custom code, so make sure you know what you're doing.&#x20;

In this example, we're going to integrate <mark style="color:blue;">`nex-duty`</mark> into a custom element.&#x20;

Here's an example of how to implement a script into a Custom Element.&#x20;

{% code overflow="wrap" %}

```lua
-- this is the same template from the "DefaultInnerHTML" option from the Config.CustomElements
local template = '<b>LEO:</b> <span style="color:{LEO_COLOUR};">{LEO}</span> <span style="color: #BBB;">/</span> <b>SAMR:</b> <span style="color:{SAMR_COLOUR};">{SAMR}</span> <span style="color: #BBB;">/</span> <b>DHS:</b> <span style="color:{DHS_COLOUR};">{DHS}</span> <span style="color: #BBB;">/</span> <b>STAFF:</b> <span style="color:{STAFF_COLOUR};">{STAFF}</span>'

-- This is jsut a helper function to set the colour depending on whether a department has on-duty units or not. The "var(--accent-color)" will use the customised colour the player has set through the /ui settings menu.
function set_colour(value)
    if value == 0 then
        return "#BBB"
    else
        return "var(--accent-color)"
    end
end

-- This queries nex-duty each interval to fetch the counts for each part of the custom element.
Citizen.CreateThread(function()
    while true do
        local leo_units = exports["nex-duty"]:getUnitsByEntities({ "sasp", "bcso", "lspd" })
        local staff_units = exports["nex-duty"]:getUnitsByEntities({ "staff" })
        local fire_units = exports["nex-duty"]:getUnitsByEntities({ "samr" })
        local dhs_units = exports["nex-duty"]:getUnitsByEntities({ "dhs" })

        -- count how many entries are in units
        local leo_count = #leo_units
        local staff_count = #staff_units
        local fire_count = #fire_units
        local dhs_count = #dhs_units

        local inner_html = template
            :gsub("{LEO}", leo_count)
            :gsub("{LEO_COLOUR}", set_colour(leo_count))
            :gsub("{STAFF}", staff_count)
            :gsub("{STAFF_COLOUR}", set_colour(staff_count))
            :gsub("{SAMR}", fire_count)
            :gsub("{SAMR_COLOUR}", set_colour(fire_count))
            :gsub("{DHS}", dhs_count)
            :gsub("{DHS_COLOUR}", set_colour(dhs_count))

        TriggerEvent("nh:server:update_custom_element", "unit_counts", inner_html)

        Wait(30000)
    end
end)

-- If you want to add and remove the ace permission from a player, so, for example, they only have the Custom Element whilst they're on duty, and it's removed once they go off, these two listening events will refresh their custom elements, so the script will recheck their permissions. If the ace permission is removed when going off duty, this will remove the custom element too. You must wait at least 1000ms for the permissions to be removed, otherwise it won't work.
AddEventHandler("nex-duty:server:go_on_duty", function()
    local src = tonumber(source)
    Citizen.Wait(1000)
    TriggerEvent("nh:server:refresh_custom_elements", src)
end)

AddEventHandler("nex-duty:server:go_off_duty", function()
    local src = tonumber(source)
    Citizen.Wait(1000)
    TriggerEvent("nh:server:refresh_custom_elements", src)
end)
```

{% endcode %}
{% endstep %}

{% step %}

### Complete

Once you've completed all of this, restart the script so the changes to the `custom_elements.lua` file are live and you're good to go.&#x20;

The code provided above is a working example, you can make the custom elements much more advanced, the possibilities are mostly limitless, so you're more than welcome to go crazy with the custom elements!
{% endstep %}
{% endstepper %}

As this requires custom code, we do not provide support for creating custom elements.

If you have any questions, let us know in our [discord server](https://discord.nexeumstudios.com/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nexeum.gitbook.io/docs/nex-hud/custom-elements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.