Custom States
Custom States¶
Several models within InvenTree support the use of custom states. Custom states extend the built-in status system by adding extra labels and colours that are displayed in the user interface.
Display Only
Custom states affect display only — they do not add new workflow steps or change business logic. Every custom state is mapped to an existing built-in state (its logical key), and the system uses that built-in state for all decisions such as availability counts, order transitions, and filtering.
Example¶
Suppose you want to track stock items that are physically present and available, but are waiting for a quality inspection before use. The built-in OK status is the closest match — the item is available — but you want it to appear distinctly in the interface.
You would create a custom state:
- Logical key:
OK— the system treats the item as available stock - Label:
Awaiting Inspection— shown in the interface instead of "OK" - Colour:
warning— displayed in amber to draw attention
The item is counted as available stock in all reports and filters, but is visually distinguished from items with a standard OK status.
Managing Custom States¶
Custom states are managed in the Admin Center under the Custom States section.
Page Reload Required
Changes to custom states are only reflected in the user interface after a full page reload.
State Fields¶
When creating a custom state, the following fields must be provided:
| Field | Description |
|---|---|
| Model | The model type this state applies to (e.g. Stock Item, Build Order) |
| Reference Status | The status class being extended (e.g. StockStatus, BuildStatus) |
| Logical Key | The built-in status value this custom state maps to for business logic |
| Key | A unique integer that identifies this custom state in the database |
| Name | An uppercase Python identifier for this state (e.g. AWAITING_INSPECTION) |
| Label | The human-readable text displayed in the interface |
| Colour | The badge colour used to display the state |
Key¶
The Key is the integer value stored in the database when this custom state is active. It must satisfy all of the following:
- Must be a positive integer
- Must not be equal to the Logical Key
- Must not conflict with any existing built-in status values for the selected model
Name¶
The Name field is used internally to identify the state. It must:
- Be uppercase (e.g.
AWAITING_INSPECTION, notawaiting_inspection) - Be a valid Python identifier (letters, digits, underscores; no spaces or hyphens)
- Not conflict with any existing status names for the selected model
Colours¶
The following colour values are available:
| Colour | Appearance |
|---|---|
primary |
Blue |
secondary |
Grey |
success |
Green |
warning |
Amber |
danger |
Red |
info |
Cyan |
dark |
Dark grey / black |