Hooks

Event hooks allow third-party resources to define new behaviour without modifying the inventory code directly.

registerHook#

lua

exports.ox_inventory:registerHook(eventName, function(payload) end, options)

Danger

Hook callbacks are intended for validation only and should avoid side effects such as modifying data, writing to a database, or triggering additional operations.

Because actions may still be in progress or may fail, modifying item or inventory state before completion can lead to race conditions or inconsistent behavior.

To avoid issues, perform state changes or follow-up logic in post-hook events.

eventName: string
callback: function(payload: table)
options?: table
- print?: boolean
  - Print to the console when triggering the event.
- itemFilter?: { [string]: true }
  - The event will only trigger for items defined as keys in a set.
- inventoryFilter?: string[]
  - The event will only trigger for inventories that match one of the patterns>) in the array.
- typeFilter?: { [string]: true }
  - The event will only trigger for inventories with one of the provided types (e.g. 'player', 'stash')

Return:

hookId: string

swapItems#

Triggered when moving any item from one slot to another, or when "giving" an item. By returning false, you can cancel the action and revert the inventory state.

Payload: table
- source: number
- action: 'move' or 'stack' or 'swap' or 'give'
- fromInventory: table or string or number
- toInventory: table or string or number
- fromType: string
- toType: string
- fromSlot: table
- toSlot?: table or number
- count: number

<details> <summary>Example</summary>

Blacklists "water" from being moved into or from gloveboxes and trunks.

lua

local hookId = exports.ox_inventory:registerHook('swapItems', function(payload)
    print(json.encode(payload, { indent = true }))
    return false
end, {
    print = true,
    itemFilter = {
        water = true,
    },
    inventoryFilter = {
        '^glove[%w]+',
        '^trunk[%w]+',
    }
})

</details>

openInventory#

Payload: table
- source: number
- inventoryId: number or string
- inventoryType: string

Triggered when a player tries to open a secondary inventory. By returning false, you can cancel the action and keep the player's inventory closed.

<details> <summary>Example</summary>

Disables gloveboxes and trunks.

lua

local hookId = exports.ox_inventory:registerHook('openInventory', function(payload)
    print(json.encode(payload, { indent = true }))
    return false
end, {
    print = true,
    inventoryFilter = {
        '^glove[%w]+',
        '^trunk[%w]+',
    }
})

</details>

openShop#

Payload: table
- source: number
- shopId: string
- shopType: string
- label: string
- slots: integer
- items: table
- groups?: table<string, number>
- coords?: vector3
- distance?: number or false

Triggered when a player tries to open a shop inventory. By returning false, you can cancel the action and keep the shop inventory closed.

<details> <summary>Example</summary>

Disable General stores.

lua

local hookId = exports.ox_inventory:registerHook('openShop', function(payload)
    print(json.encode(payload, { indent = true }))
    return false
end, {
    print = true,
    inventoryFilter = {
        '^General'
    }
})

</details>

createItem#

Payload: table
- inventoryId?: number or string
- metadata: table
- item: table
- count: number

Triggered when an item is created, either by buying it, using AddItem, or when converting inventory data. By returning a table you can modify or replace the metadata given to an item.

Post-hook events are not necessary for this event, but are still recommended

<details> <summary>Example</summary>

Sets the label for "water" to "Mineral Water".

lua

local hookId = exports.ox_inventory:registerHook('createItem', function(payload)
    print(json.encode(payload, { indent = true }))
    local metadata = payload.metadata
    metadata.label = 'Mineral Water'
    return metadata
end, {
    print = true,
    itemFilter = {
        water = true
    }
})

</details>

buyItem#

Payload: table
- source: number
- shopType: string
- shopId: number
- toInventory: number
- toSlot: number
- itemName: string
- metadata: table
- count: number
- price: number
- totalPrice: number
- currency?: string

Triggered when an item is about to be purchased and can return false to prevent the transaction.

<details> <summary>Example</summary>

Prevents players from purchasing items at General stores.

lua

local hookId = exports.ox_inventory:registerHook('buyItem', function(payload)
    print(json.encode(payload, { indent = true, sort_keys = true }))
    return false
end, {
    print = true,
    itemFilter = {
        water = true
	  },
})

</details>

craftItem#

Payload: table
- source: number
- benchId: number | string
- benchIndex: number
- recipe: table
 - count: number
 - duration: number
 - ingredients: table<string, number>
 - name: string
 - slot: number
 - weight: number
- toInventory: number
- toSlot: number

<details> <summary>Example</summary>

Prevent lockpicks from being crafted by players.

lua

local hookId = exports.ox_inventory:registerHook('craftItem', function(payload)
    print(json.encode(payload, { indent = true, sort_keys = true }))
    return false
end, {
    print = true,
	itemFilter = {
		lockpick = true
	},
})

</details>

usingItem#

Triggered when an item is about to be used. By returning false, you can fully prevent it from being used.

Payload: table
- source: number
- inventoryId: number
- item: table
  - name: string
  - label: string
  - weight: number
  - count: number
  - stack: boolean
  - close: boolean
  - slot: number
  - metadata: table
- consume: number

<details> <summary>Example</summary>

Prevent the player from using the "water" item.

lua

local hookId = exports.ox_inventory:registerHook('usingItem', function(payload)
    print(json.encode(payload, { indent = true, sort_keys = true }))
    return false
end, {
    print = true,
    itemFilter = {
        water = true
    }
})

</details>

removeHooks#

Removes a hook created by the invoking resource with the the specified id. If no id is specified then all hooks registered by the resource are removed.

lua

exports.ox_inventory:removeHooks(id)

id?: string

Post-hook events#

Post-hook events let you register an event handler that runs after all hooks have finished and the action has either completed successfully or been rejected.

Use the hookId returned by registerHook with AddEventHandler to handle post-hook logic.

lua

---Use filter logic so only relevant inventories trigger the post-hook event.
local hookId = exports.ox_inventory:registerHook('swapItems', nil, {
    inventoryFilter = {
        '^glove[%w]+',
        '^trunk[%w]+',
    }
})

---Print everytime an item is moved to or from a vehicle inventory.
---Success will be false if the hook rejected the action or it failed elsewhere.
AddEventHandler(hookId, function(success, payload)
    print(hookId, success)
    lib.print.info(payload)
end)