> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tetherdata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dimensions

> Configuring product dimensions and attributes in Tether

# Dimensions

Dimensions define the variable attributes of your products. They're the backbone of variant management, enabling you to create and organize products with different sizes, colors, materials, and more.

## What Are Dimensions?

A dimension is a product attribute that varies across SKUs within a collection. Common examples:

| Dimension    | Purpose             | Example Values                 |
| ------------ | ------------------- | ------------------------------ |
| **Size**     | Physical size       | XS, S, M, L, XL, XXL           |
| **Color**    | Visual appearance   | Red, Blue, Black, White        |
| **Material** | Composition         | Cotton, Polyester, Leather     |
| **Length**   | Measurement variant | Short, Regular, Long           |
| **Width**    | Fit type            | Narrow, Standard, Wide         |
| **Flavor**   | Product variety     | Vanilla, Chocolate, Strawberry |
| **Scent**    | Fragrance type      | Lavender, Citrus, Unscented    |

## Dimensions vs. Other Attributes

Understanding when to use dimensions:

| Use Dimensions When                    | Use Other Fields When              |
| -------------------------------------- | ---------------------------------- |
| Attribute varies within a product line | Attribute is unique to each SKU    |
| You need to filter by this attribute   | It's just informational            |
| Products share the attribute values    | Values are product-specific        |
| You want to generate SKU variants      | You're describing a single product |

**Example:**

* "Size" should be a dimension (T-Shirts come in S, M, L)
* "Weight" might be a SKU field (each product has one specific weight)

## The Dimensions Dashboard

Access the dimensions dashboard from **SKUs** → **Dimensions** in the main navigation.

### Dashboard Features

| Feature                 | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| **Dimension Hierarchy** | Shows the current ordering of dimensions with drag-and-drop reordering |
| **Dimension List**      | All dimensions with their ranges, values, and position                 |
| **Search**              | Find dimensions by name or description                                 |
| **New Dimension**       | Create new dimensions                                                  |

### Current Dimension Hierarchy

The dashboard prominently displays the **Current Dimension Hierarchy** card, which shows the order dimensions are applied throughout the application. This ordering affects SKU code generation and how variants are organized.

* Click **Reorder** to enter drag mode
* Drag dimensions using the grip handle to rearrange
* Click **Save Order** to persist changes, or **Cancel** to discard

<Info>
  The Reorder button is only available when you have at least 2 dimensions.
</Info>

## Creating Dimensions

### From the Dimensions Dashboard

<Steps>
  <Step title="Navigate to Dimensions">
    Go to **SKUs** → **Dimensions** in the navigation menu
  </Step>

  <Step title="Click New Dimension">
    Click the **New Dimension** button
  </Step>

  <Step title="Enter Basic Information">
    * **Dimension Name** (required): Display name (e.g., "Size", "Color", "Material")
    * **Description** (optional): Explain the dimension's purpose
  </Step>

  <Step title="Add Values">
    Add values with both a name and a SKU code:

    * **Value Name**: Human-readable label (e.g., "Small")
    * **SKU Code**: Short identifier used in SKU generation (e.g., "SM")
    * Press **Enter** or click **+** to add each value
    * At least one value is required
  </Step>

  <Step title="Create Dimension">
    Click **Create Dimension** to save. A default "Standard" range is automatically created containing your values.
  </Step>
</Steps>

<Info>
  Dimensions are organization-wide, not collection-specific. Once created, dimensions can be assigned to any collection from the collection's **Dimensions** tab.
</Info>

### From a Collection

You can also assign existing dimensions to a collection:

<Steps>
  <Step title="Open the Collection">
    Navigate to the collection's detail page
  </Step>

  <Step title="Go to Dimensions Tab">
    Select the **Dimensions** tab
  </Step>

  <Step title="Assign Dimensions">
    Use the dimension manager to assign existing dimensions to the collection
  </Step>
</Steps>

## Dimension Detail Page

Click on any dimension in the list to open its detail page. The detail page shows:

* **Dimension Details**: Name, description, default range, and total range count
* **Dimension Ranges**: Cards for each range showing its values

You can edit the dimension's name and description by clicking the **Edit** button in the Dimension Details card.

## Ranges and Values

Dimensions use a **range-based** structure. Each dimension has one or more ranges, and each range contains a set of values. This allows the same dimension to have different value sets for different contexts.

**Example:** A "Size" dimension might have:

* **US Sizes** range: XS, S, M, L, XL
* **EU Sizes** range: 34, 36, 38, 40, 42

When you create a dimension, a default "Standard" range is automatically created with your initial values.

### Adding a Range

<Steps>
  <Step title="Open the Dimension">
    Click on a dimension to open its detail page
  </Step>

  <Step title="Click Add Range">
    Click the **Add Range** button
  </Step>

  <Step title="Enter Range Details">
    * **Range Name** (required): e.g., "EU Sizes"
    * **Description** (optional): Explain the range's purpose
    * Add values with names and SKU codes
  </Step>

  <Step title="Save">
    Click **Add Range** to save
  </Step>
</Steps>

### Editing Values in a Range

<Steps>
  <Step title="Open the Dimension">
    Click on a dimension to open its detail page
  </Step>

  <Step title="Click Edit Values">
    On the range card, click **Edit Values**
  </Step>

  <Step title="Make Changes">
    In the modal:

    * Click **Add Value** to add new values (name + SKU code required)
    * Click the edit icon to modify existing values
    * Click the delete icon to remove values
    * New and modified items show status badges
  </Step>

  <Step title="Save">
    Click **Save Changes** — all changes are batched and saved together
  </Step>
</Steps>

<Info>
  Changing a value's name doesn't change existing SKUs that use it. The relationship is by ID, not name.
</Info>

### Validation Rules

* Value name and SKU code are both required
* SKU codes must be unique within a range
* SKU codes can be up to 20 characters
* SKU codes can contain letters, numbers, and: `- . / _ % # ( ) : + = @`
* Duplicate value names within a range are not allowed

## Dimension Hierarchy

The dimension hierarchy determines the order in which dimensions appear throughout the application, including how product variants are organized and SKU codes are generated.

### Viewing the Hierarchy

The **Current Dimension Hierarchy** section on the dimension dashboard shows all active dimensions in their current order. Each dimension displays its position number and name.

<Info>
  The dimension hierarchy determines the order used throughout the application for organizing product variants and generating SKU codes.
</Info>

### Reordering the Hierarchy

<Steps>
  <Step title="Click Reorder">
    Click the **Reorder** button in the hierarchy section header (requires at least 2 dimensions)
  </Step>

  <Step title="Drag and Drop">
    Drag dimensions to rearrange them into the desired order. A drag handle appears next to each dimension.
  </Step>

  <Step title="Save or Cancel">
    Click **Save Order** to apply the new hierarchy, or **Cancel** to discard changes
  </Step>
</Steps>

<Warning>
  Reordering the hierarchy will affect future SKU generation. Existing SKU codes are not changed.
</Warning>

## Value SKU Codes

Each dimension value has a **SKU code** — a short identifier used in SKU code generation. SKU codes are set when you create or edit values.

### SKU Code Rules

* Maximum 20 characters
* Allowed characters: letters, numbers, and `- . / _ % # ( ) : + = @`
* Must be unique within a range
* Automatically converted to uppercase

### Best Practices

| Guideline       | Good           | Bad                   |
| --------------- | -------------- | --------------------- |
| Keep short      | "M", "BLU"     | "MEDIUM", "BLUECOLOR" |
| Be consistent   | All 2-3 chars  | Mix of lengths        |
| Avoid ambiguity | "NVY" for Navy | "N" (too vague)       |
| Use uppercase   | "XL"           | "xl"                  |

### Examples

| Dimension | Value        | SKU Code |
| --------- | ------------ | -------- |
| Size      | Extra Small  | XS       |
| Size      | Small        | S        |
| Size      | Medium       | M        |
| Color     | Navy Blue    | NVY      |
| Color     | Forest Green | FGR      |
| Material  | 100% Cotton  | COT      |

## Dimensions and SKU Generation

Dimensions power the SKU Generator, which creates variant combinations automatically.

### How It Works

1. Define dimensions with values and SKU codes
2. Open the SKU Generator from a collection
3. Select which dimension values to include
4. The generator creates all combinations

**Example:**

* Size: S, M, L (3 values)
* Color: Red, Blue (2 values)
* Result: 6 SKUs (3 × 2)

The dimension hierarchy order determines how SKU codes are assembled. For example, if Size is first and Color is second, the generated code might be `TSH-M-BLU` (collection code + size code + color code).

## Dimension Filtering

Dimensions appear as filters on the SKU dashboard. Each active dimension with values becomes a filter group in the filter panel.

### Tri-State Filtering

Dimension filters support three states:

| State           | Visual          | Action                               |
| --------------- | --------------- | ------------------------------------ |
| **Indifferent** | Empty checkbox  | Don't filter by this value (default) |
| **Include**     | Green checkmark | Show only SKUs with this value       |
| **Exclude**     | Red X           | Hide SKUs with this value            |

Click a value once to include it, click again to exclude it, and click a third time to return to indifferent.

## Common Dimension Patterns

<AccordionGroup>
  <Accordion title="Apparel">
    **Typical dimensions:**

    * Size (XS through XXL)
    * Color (brand-specific palette)
    * Length (Short, Regular, Long)
    * Fit (Slim, Regular, Relaxed)

    **Tips:**

    * Use consistent size scales
    * Include size charts in documentation
    * Consider regional size variations
  </Accordion>

  <Accordion title="Food & Beverage">
    **Typical dimensions:**

    * Flavor (Vanilla, Chocolate, etc.)
    * Size (Small, Medium, Large or oz/ml)
    * Pack Size (Single, 6-pack, 12-pack)

    **Tips:**

    * Include unit information
    * Consider dietary variants (Regular, Sugar-Free)
  </Accordion>

  <Accordion title="Electronics">
    **Typical dimensions:**

    * Storage (64GB, 128GB, 256GB)
    * Color (Space Gray, Silver, Gold)
    * Configuration (Base, Pro, Max)

    **Tips:**

    * Use technical specifications in codes
    * Be precise with measurements
  </Accordion>

  <Accordion title="Home Goods">
    **Typical dimensions:**

    * Size (Twin, Full, Queen, King)
    * Color/Pattern (Solid, Striped, Floral)
    * Material (Cotton, Linen, Microfiber)

    **Tips:**

    * Include standard measurements
    * Note regional naming differences
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Dimension Not Appearing in Filters

**Cause:** No SKUs have values for this dimension

**Solution:**

1. Assign dimension values to SKUs
2. Or use the SKU Generator to create variants with dimension values

### Duplicate SKU Codes

**Cause:** Same SKU code used within a range

**Solution:**

* SKU codes only need to be unique within a single range
* Different ranges can have overlapping SKU codes
* If this causes confusion, use more descriptive codes

### Cannot Reorder Hierarchy

**Cause:** Only one dimension exists

**Solution:**

* The **Reorder** button requires at least two dimensions
* Create additional dimensions before reordering

## Next Steps

<CardGroup cols={2}>
  <Card title="Collections" icon="folder" href="/product-catalog/collections/managing">
    Manage collections that use dimensions
  </Card>

  <Card title="Creating SKUs" icon="plus" href="/product-catalog/skus/creating-skus">
    Use dimensions to generate SKU variants
  </Card>

  <Card title="Product Hierarchy" icon="sitemap" href="/product-catalog/hierarchy">
    Set up categorization for reporting
  </Card>

  <Card title="Filtering" icon="filter" href="/product-catalog/skus/filtering">
    Use dimensions in filters
  </Card>
</CardGroup>