orcaqubits/saleor-attributes

Saleor Attributes

Before writing code

Fetch live docs:

1. Fetch https://docs.saleor.io/docs/developer/products for product and attribute overview
2. Web-search site:docs.saleor.io attribute types DROPDOWN MULTISELECT NUMERIC for attribute type reference
3. Web-search site:docs.saleor.io product type attributes variant selection for product type configuration
4. Web-search site:docs.saleor.io attribute filtering products for attribute-based filtering
5. 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 for attributes that make sense as customer-facing filters
• Use NUMERIC type with units for measurable properties (weight, length) to enable range filtering
• Create separate product types for structurally different products (clothing vs electronics)
• Use page types to model structured content (blog posts, FAQs) without a separate CMS
• Translate attribute names and values for multi-language storefronts

Fetch the Saleor attributes documentation for exact attribute type behaviors, product type configuration patterns, and filtering query syntax before implementing.