Home Documentation & Help
Steamworks Documentation
Steam Inventory Item Tags
Item tags allow us to show the user an "Advanced Filter" dialog for items, including the inventory
and market search views. A player can quickly narrow a view down to items of a given rarity, or only items that apply to their character class.

To use tags, first define the categories and tags directly in the Item Definitions, then provide user-visible
localized strings in English and any other languages you plan to support. Tags that do not have at least an
English localization string will be ignored by inventory features.

The values used in the item definition should be short, simple text tokens. These tokens are used as a key to identify the localized strings in each language. The tokens will never be shown to the user directly.

Item Tag Localization

Once you've defined tags for your items, to make them visible to users you must provide user-visible translations
at least in English, but preferably in all supported languages. This can be set as part of your SteamWorks configuration, on the Inventory Service page for your application.


Item Tag Format

The tag field should be provided as a list of categorized tokens, separated by the ";" character.
Each token consists of a category token and a value token, separated by the ":" character.

<tag_list>: <tag_pair> { ";" <tag_pair> } <tag_pair>: <category_token> ":" <tag_token>

Item Tag Example

"tags":"class:elf;farms:potato;rarity:legendary;type:character;handed:ambi" ... "tags":"class:troll;farms:gold;rarity:common;type:character;handed:left"

Per-Item Tags

When an item is created from a generator, playtimegenerator, or bundle, you can assign it tags that it will keep throughout its lifetime and persist across ownership changes.

A simple way to assign tags would be to define them in the generating item definition--basically anything in the tags field for generator or playtimegenerator item definitions would be copied over wholesale to any created item.


Generator A has a 10% chance to create an item from Generator Legendary, and a 90% chance to create an item from Generator Common. Generator A also happens to apply the color:red tag. Generator Legendary applies the tag quality:legendary and creates sword or shield items, while Generator Common applies the tag quality:common and also creates sword or shield items.

itemdefid: 10 type: item name: Sword itemdefid: 11 type: item name: Shield itemdefid: 100 type: generator name: Generator A bundle: 101x1;102x9 tags: color:red itemdef: 101 type: generator name: Generator Legendary bundle: 10;11 tags: quality:legendary itemdef: 102 type: generator name: Generator Common bundle: 10;11 tags: quality:common

Another way to assign tags would be to use the tag_generator item definition type. In this special item definition (that doesn't actually generate items) you would define the set of tags to pick from and their probabilities. In a generator, playtimegenerator, or bundle item definition, you'd need to set the tag_generators field with the item definition ids of all the tag generators. Those tag generators will be applied to all downstream items.

Tag Generator Example

Generator A creates either a sword or a shield, applies the color:red tag, and then applies the Tag Generator Quality and Tag Generator FX to the new item. Tag Generator Quality has a 10% chance to add the quality:legendary tag and a 90% chance to apply the quality:common tag. Tag Generator FX has an equal chance to apply the tags fx:flames, fx:sparks, or fx:lasers. In the end you could end up with "Legendary Red Shield with Flames" or a "Common Red Sword with Lasers."

itemdefid: 10 type: item name: Sword itemdefid: 11 type: item name: Shield itemdefid: 100 type: generator name: Generator A bundle: 10;11 tags: color:red tag_generators: 101;102 itemdefid: 101 type: tag_generator name: Tag Generator Quality tag_generator_name: quality tag_generator_values: legendary:1;common:9 itemdefid: 102 type: tag_generator name: Tag Generator FX tag_generator_name: fx tag_generator_values: flames;sparks;lasers

The format for the tag_generators field is a list of all item definition ids of the tag generators you want applied, separated by the ";" character.

For tag_generator item definitions, you'll need to define both the tag_generator_name field and tag_generator_values field.

The tag_generator_name field is the same thing as the category token defined above.

For the tag_generator_values field, it is a list of tag_token:chance separated by the ";" character. If chance is omitted it defaults to 1.