Saleor Attributes
Before writing code
Fetch live docs:
- Fetch
https://docs.saleor.io/docs/developer/products for product and attribute overview
- Web-search
site:docs.saleor.io attribute types DROPDOWN MULTISELECT NUMERIC for attribute type reference
- Web-search
site:docs.saleor.io product type attributes variant selection for product type configuration
- Web-search
site:docs.saleor.io attribute filtering products for attribute-based filtering
- Web-search
site:docs.saleor.io page types attributes for content page attributes
Attribute System Overview
Saleor uses a typed attribute system to define flexible product schemas without database migrations. Attributes are attached to product types and page types, providing structured metadata for products, variants, and content pages.
| Concept | Purpose |
|---|
| Attribute | A named, typed field (e.g., "Color", "Size", "Material") |
| Attribute value | A specific value for an attribute (e.g., "Red", "XL", "Cotton") |
| Product type | A template that defines which attributes a product has |
| Page type | A template that defines which attributes a content page has |
| Variant selection attribute | An attribute used to distinguish product variants |
Attribute Types
| Type | Input | Storage | Use Case |
|---|
DROPDOWN | Single select from predefined values | String reference | Color, brand, material |
MULTISELECT | Multiple select from predefined values | String references | Features, tags, certifications |
RICH_TEXT | Rich text editor (JSON) | JSON (EditorJS) | Long descriptions, care instructions |
PLAIN_TEXT | Simple text input | String | Short notes, SKU prefix |
NUMERIC | Number input with optional unit | Decimal | Weight, dimensions, capacity |
BOOLEAN | True/false toggle | Boolean | Is organic, is fragile |
DATE | Date picker | Date | Expiry date, release date |
DATE_TIME | Date and time picker | DateTime | Event time, availability window |
FILE | File upload | File reference | Spec sheets, certificates |
REFERENCE | Reference to another entity | Entity ID | Related product, linked page |
SWATCH | Color swatch (hex or image) | String + optional image | Visual color selection |
Product Types
A product type defines the schema for a group of products:
| Product Type Field | Purpose |
|---|
name | Product type name (e.g., "T-Shirt", "Laptop") |
productAttributes | Attributes shown on the product level |
variantAttributes | Attributes that define variant differences |
isShippingRequired | Whether products of this type need shipping |
isDigital | Whether products are digital downloads |
taxClass | Tax classification for products of this type |
weight | Default weight for products of this type |
Product Attributes vs Variant Selection Attributes
| Category | Scope | Example |
|---|
| Product attributes | Same for all variants of a product | Brand, material, care instructions |
| Variant attributes (non-selection) | Per variant, but not for customer selection | Internal SKU code |
| Variant selection attributes | Per variant, presented to the customer for selection | Size, color |
Variant selection attributes generate the variant picker on the storefront (e.g., size/color dropdowns).
Attribute Values
| Value Aspect | Detail |
|---|
| Predefined | Created in advance for DROPDOWN, MULTISELECT, SWATCH types |
| Dynamic | Entered per product for PLAIN_TEXT, RICH_TEXT, NUMERIC, DATE types |
| Sortable | Values can be reordered within an attribute |
| Translatable | Values support multi-language translations |
| Slug | URL-safe identifier auto-generated from the value name |
Rich Text Values
Rich text attributes use the EditorJS JSON format:
| Block Type | Purpose |
|---|
paragraph | Text paragraph |
header | Heading (h1-h6) |
list | Ordered or unordered list |
image | Embedded image |
Page Types
Page types work like product types but for content pages (CMS):
| Page Type Field | Purpose |
|---|
name | Page type name (e.g., "Blog Post", "FAQ") |
attributes | Attributes attached to pages of this type |
Content pages use the same attribute types as products, enabling structured content management without a separate CMS.
Attribute Input Types
The inputType field controls how an attribute is presented in the Dashboard:
| Input Type | Attribute Types | Dashboard UI |
|---|
DROPDOWN | DROPDOWN | Single-select dropdown |
MULTISELECT | MULTISELECT | Multi-select chips |
PLAIN_TEXT | PLAIN_TEXT | Simple text field |
RICH_TEXT | RICH_TEXT | EditorJS rich text editor |
NUMERIC | NUMERIC | Number input with unit selector |
BOOLEAN | BOOLEAN | Toggle switch |
DATE | DATE | Date picker |
DATE_TIME | DATE_TIME | Date and time picker |
FILE | FILE | File upload widget |
REFERENCE | REFERENCE | Entity search and select |
SWATCH | SWATCH | Color picker or image upload |
Filtering Products by Attributes
Attributes enable faceted navigation on the storefront:
| Filter Parameter | Type | Purpose |
|---|
attributes | list | Filter by attribute slug and values |
attributes.slug | string | Attribute identifier |
attributes.values | string[] | Attribute value slugs to match |
attributes.valuesRange | object | Numeric range filter (min/max) |
attributes.date | object | Date range filter |
attributes.dateTime | object | DateTime range filter |
attributes.boolean | boolean | Boolean attribute filter |
Faceted Navigation Pattern
| Step | Action |
|---|
| 1 | Query available attributes for the product type or category |
| 2 | Display attribute values as filter options (checkboxes, sliders) |
| 3 | Build attributes filter from user selections |
| 4 | Pass filter to products query |
| 5 | Update available filter values based on current selection (count-aware) |
Creating Attributes via GraphQL
| Mutation | Purpose |
|---|
attributeCreate | Create a new attribute with type and values |
attributeUpdate | Modify attribute settings |
attributeDelete | Remove an attribute |
attributeValueCreate | Add a new value to an attribute |
attributeValueUpdate | Modify an attribute value |
attributeValueDelete | Remove an attribute value |
attributeReorderValues | Change the sort order of values |
productTypeCreate | Create a product type with attribute assignments |
productTypeUpdate | Modify product type attribute assignments |
Attribute Creation Fields
| Input Field | Required | Purpose |
|---|
name | Yes | Display name |
slug | No | Auto-generated from name if omitted |
type | Yes | PRODUCT_TYPE or PAGE_TYPE |
inputType | Yes | One of the attribute input types |
values | No | Initial predefined values (for DROPDOWN, MULTISELECT) |
valueRequired | No | Whether the attribute must have a value |
isVariantOnly | No | Restrict to variant-level only |
visibleInStorefront | No | Whether the attribute is public |
filterableInStorefront | No | Whether the attribute appears in storefront filters |
filterableInDashboard | No | Whether the attribute appears in Dashboard filters |
availableInGrid | No | Whether the attribute appears in Dashboard product grid |
unit | No | Measurement unit for NUMERIC type |
Best Practices
- Use DROPDOWN for attributes with a fixed set of values (colors, sizes, brands)
- Use variant selection attributes only for attributes that the customer chooses (size, color)
- Keep product attributes for shared information that does not vary per variant (brand, material)
- Enable
filterableInStorefront only
