UnitId

This article is about the World of Warcraft API. For units in Warcraft RTS games, see Unit (RTS).

A unitId (or unit token^[1]) identifies a unit by their relationship to the player as a target, party member, pet, or other such role. Several API functions accept unitId as an argument for whom the action applies, though some functions only accept a subset of possible values. UnitIds are case insensitive.

Base Values

"arenaN": Opposing arena member with index N (1,2,3,4 or 5).

"bossN": The active bosses of the current encounter if available N (1,2,3...,8).

"focus": The current player's focus target as selected by the /focus command.

"mouseover": The unit which the mouse is currently (or was most recently) hovering over.

"none": A valid unit token that always refers to no unit. UnitName will return "Unknown, nil" for this UnitID. Use to force a macro to not auto self-cast (/cast [target=none] Healing Wave).

"partyN": The Nth party member excluding the player (1,2,3 or 4).

"partypetN": The pet of the Nth party member (N is 1,2,3, or 4).

"pet": The current player's pet.

"player": The current player.

"raidN": The raid member with raidIndex N (1,2,3,...,40).

"raidpetN": The pet of the raid member with raidIndex N (1,2,3,...,40)

"target": The currently targeted unit. May be overridden in macros by unit specified as a value of respective Secure Button attribute.

"vehicle": The current player's vehicle.

"nameplateN"": The Nth nameplate (1,2,3,...,40). Cannot be targeted by spells or commands such as /target nameplate1 or /cast [target=nameplate1] Healing Wave.

"spectated<T><N>": The Nth spectated unit (1,2,3,...,15) for either Team "a" or "b", such as "spectatedb2" for the second unit on team B. Only present in commentator mode.

"spectatedpet<T><N>": The pet of the Nth spectated unit (1,2,3,...,15) for either Team "a" or "b", such as "spectatedpetb2" for the second units' pet on team B. Only present in commentator mode.

Soft Targeting

This section concerns content related to Dragonflight.

Soft targets are additional units that are automatically selected through an in-world unit scan. These exist separately from the standard "target" unit, which is referred to as a locked target.

"anyenemy": Resolves to either the "target" unit or "softenemy" target, with "target" being higher priority.
"anyfriend": Resolves to either the "target" unit or "softfriend" target, with "target" being higher priority.
"anyinteract": Resolves to either the "target" unit or "softinteract" target, with "target" being higher priority.
"softenemy": The current soft target that is hostile towards the player.
"softfriend": The current soft target that is friendly towards the player.
"softinteract": The current soft target that can be interacted with. This may be an NPC such as a questgiver or merchant, or a game object like a mailbox or a gathering node.

Others

The following units also appear in some very specific places (Vendor interactions, for example) or functions.

"npc": The NPC with which the player is currently interacting. You must be interacting with the NPC for this to work (e.g. the quest, flight path, merchant, gossip, or bank frame is open).

"questnpc": The quest giver NPC with which the player is currently interacting. In most cases this will be identical to the "npc" unit.

player name: As returned by UnitName, GetGuildRosterInfo, GetFriendInfo, COMBAT LOG EVENT, etc. This must be spelled exactly and will be invalid if the named player is not a part of your party or raid. As with all other UnitIDs, it is not case sensitive.

Target of unit

Append the suffix target to any UnitId to refer its target (e.g. "pettarget" is the target of your pet). This appending can be repeated indefinitely (e.g. "playertargettarget"), though you will observe an attendant performance hit if you overdo it, as the game engine has to jump from target to target.

If you are using a party or raid member's name as a unit, you need to use hyphens to separate the target chain (e.g. "Cogwheel-target-target").

Examples

"raid7target": Refers to the 7th raid member's target.

"party1targettarget": Refers to the first party member (not the player, but the first person in the player's party frames)'s target's target.

"targettargetpettarget": Refers to the player's target's target's pet's target. Will refer to the player's target if the player's target and the player's pet are both targeting the player.

"mouseoverpettarget": Refers the unit being moused over's pet's target.

"playertarget": The same as simply using "target". Using "playertarget" is not as efficient as simply using "target".

"Cogwheel": Refers to Cogwheel if he is in the player's party/raid.

"Cogwheel-target": Refers to Cogwheel's target if he is in the player's party/raid.

"Cogwheel-pet-target": Refers to Cogwheel's pet's target if he is in the player's party/raid.

Details

Many of the functions which take a UnitId only provide useful results for a subset of ID's. Other functions will only provide information for friendly targets (or those upon which a power is active).
Some functions return different values if the unit is close enough to be 'visible' to your client (not necessarily in line of sight), as can be determined with UnitIsVisible(unit).

Patch changes

Patch 10.0.0 (2022-10-25): Added anyenemy, anyfriend, anyinteract, softenemy, softfriend, and softinteract.
Patch 7.0.3 (2016-07-19): Added nameplateN.
Patch 3.3.0 (2009-12-08): Added bossN.
Patch 2.0.1 (2006-12-05): Added focus.
Patch 1.5.0 (2005-06-07): Added partypetN and raidpetN.