# convert-dimension

## Interface

```typescript
interface parser {
  name: 'convert-dimension';
  options: {
    toFormat:
      | '%' 
      | 'px' 
      | 'em' 
      | 'rem' 
      | 'pt' 
      | 'pc' 
      | 'in' 
      | 'cm' 
      | 'mm' 
      | 'ex' 
      | 'cap' 
      | 'ch' 
      | 'ic' 
      | 'lh' 
      | 'rlh' 
      | 'vw' 
      | 'svw' 
      | 'lvw' 
      | 'dvw' 
      | 'vh' 
      | 'svh' 
      | 'lvh' 
      | 'dvh' 
      | 'vi' 
      | 'svi' 
      | 'lvi' 
      | 'dvi' 
      | 'vb' 
      | 'svb' 
      | 'lvb' 
      | 'dvb' 
      | 'vmin' 
      | 'svmin' 
      | 'lvmin' 
      | 'dvmin' 
      | 'vmax' 
      | 'svmax' 
      | 'lvmax' 
      | 'dvmax'
      | null;
    baseValue?: {
      rem?: number
    };
    applyTo?: SDTFQuery;
    applyToKeys?: {
      textStyle?: Array<'fontSize' | 'lineHeight' | 'letterSpacing' | 'paragraphSpacing'| 'textIndent'>,
      shadow?: Array<'offsetX' | 'offsetY' | 'blurRadius' | 'spreadRadius'>,
      border?: Array<'width' | 'rectangleCornerRadii'>,
    };
    excludeFormats?: array;
    includeFormats?: array;
  };
}
```

## Options

<table><thead><tr><th width="206">Parameter</th><th width="127.33333333333331">Required</th><th width="341">Type</th><th width="136">Default</th><th width="237">Description</th></tr></thead><tbody><tr><td><code>toFormat</code></td><td>required</td><td><pre class="language-typescript"><code class="lang-typescript">| '%' 
| 'px' 
| 'em' 
| 'rem' 
| 'pt' 
| 'pc' 
| 'in' 
| 'cm' 
| 'mm' 
| 'ex' 
| 'cap' 
| 'ch' 
| 'ic' 
| 'lh' 
| 'rlh' 
| 'vw' 
| 'svw' 
| 'lvw' 
| 'dvw' 
| 'vh' 
| 'svh' 
| 'lvh' 
| 'dvh' 
| 'vi' 
| 'svi' 
| 'lvi' 
| 'dvi' 
| 'vb' 
| 'svb' 
| 'lvb' 
| 'dvb' 
| 'vmin' 
| 'svmin' 
| 'lvmin' 
| 'dvmin' 
| 'vmax' 
| 'svmax' 
| 'lvmax' 
| 'dvmax'
| null
</code></pre></td><td></td><td>The target dimension format to convert to.</td></tr><tr><td><code>baseValue</code></td><td><code>false</code></td><td><pre class="language-typescript"><code class="lang-typescript">{ rem: number }
</code></pre></td><td></td><td></td></tr><tr><td><code>applyTo</code></td><td><code>false</code></td><td><pre class="language-typescript"><code class="lang-typescript">| { collection: string | true }
| { group: string | true }
| { token: string | true }
| SDTFQuery
</code></pre></td><td><pre><code>{ token: true }
</code></pre></td><td>The selection where to apply the transformation.<br><br><code>collection</code>, <code>group</code>, <code>token</code> take a Regex string or <code>true</code> to select anything of the kind.<br><br>An <code>SDTFQuery</code> can be used for advance use cases.</td></tr><tr><td><code>applyToKeys</code></td><td><code>false</code></td><td><pre class="language-typescript"><code class="lang-typescript">{
  textStyle?: Array&#x3C;'fontSize' | 'lineHeight' | 'letterSpacing' | 'paragraphSpacing'| 'textIndent'>,
  shadow?: Array&#x3C;'offsetX' | 'offsetY' | 'blurRadius' | 'spreadRadius'>,
  border?: Array&#x3C;'width' | 'rectangleCornerRadii'>,
}
</code></pre></td><td></td><td>Select composite tokens sub-values to convert</td></tr><tr><td><code>excludeFormats</code></td><td><code>false</code></td><td>array</td><td></td><td>List of dimension formats you don't want to convert.</td></tr><tr><td><code>includeFormats</code></td><td><code>false</code></td><td>array</td><td></td><td>List of dimension formats you only want to convert.</td></tr></tbody></table>

## Examples

### Basic usage

{% tabs %}
{% tab title="Input" %}

<pre class="language-json" data-line-numbers><code class="lang-json">{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 4,
</strong><strong>            "unit": "px"
</strong>          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 8,
</strong><strong>            "unit": "px"
</strong>          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 12,
</strong><strong>            "unit": "px"
</strong>          }
        }
      }
    }
  }
}
</code></pre>

{% endtab %}

{% tab title="Config" %}
We convert all dimensions from our SDTF graph in `rem`.

We then generate our transformed SDTF graph in a JSON file thanks to the [to-sdtf](/reference/parsers/to-sdtf.md) parser.

{% code title=".specifyrc.json" lineNumbers="true" %}

```json5
{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert spacing in rem and generate tokens in JSON",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "toFormat": "rem"
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

<pre class="language-json" data-title="tokens.json" data-line-numbers><code class="lang-json">{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 0.25,
</strong><strong>            "unit": "rem"
</strong>          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 0.5,
</strong><strong>            "unit": "rem"
</strong>          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 0.75,
</strong><strong>            "unit": "rem"
</strong>          }
        }
      }
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

### Generate unitless dimension tokens

{% tabs %}
{% tab title="Input" %}
{% code lineNumbers="true" %}

```json
{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 8,
            "unit": "px"
          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 12,
            "unit": "px"
          }
        }
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Config" %}
{% code title=".specifyrc.json" lineNumbers="true" %}

```json
{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert spacing in rem and generate tokens in JSON",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "toFormat": null
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

<pre class="language-json" data-title="tokens.json" data-line-numbers><code class="lang-json">{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.25,
<strong>            "unit": null
</strong>          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.5,
<strong>            "unit": null
</strong>          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.75,
<strong>            "unit": null
</strong>          }
        }
      }
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

### Convert text style's font-size from px to rem

{% tabs %}
{% tab title="Input" %}
{% code lineNumbers="true" %}

```json
{
  "Text styles": {
    "Body": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "family": "Neue Haas Grotesk Text Pro",
            "postScriptName": "Neue Haas Grotesk Text Pro",
            "weight": "roman",
            "style": "normal",
            "files": []
          },
          "fontSize": {
            "value": 14,
            "unit": "px"
          },
          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 150,
            "unit": "%"
          },
          "letterSpacing": {
            "value": 0.2,
            "unit": "px"
          },
          "paragraphSpacing": {
            "value": 0,
            "unit": "px"
          },
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": "none",
          "textIndent": {
            "value": 0,
            "unit": "px"
          },
          "textTransform": "none"
        }
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Config" %}
{% code title=".specifyrc.json" lineNumbers="true" %}

```json
{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert font-sizes to rem",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "applyToKeys": {
              "textStyle": [
                "fontSize"
              ]
            },
            "toFormat": "rem"
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "public/tokens.json"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

<pre class="language-json" data-title="tokens.json" data-line-numbers><code class="lang-json">{
  "Text styles": {
    "Body": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "family": "Neue Haas Grotesk Text Pro",
            "postScriptName": "Neue Haas Grotesk Text Pro",
            "weight": "roman",
            "style": "normal",
            "files": []
          },
<strong>          "fontSize": {
</strong><strong>            "value": 0.875,
</strong><strong>            "unit": "rem"
</strong><strong>          },
</strong>          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 150,
            "unit": "%"
          },
          "letterSpacing": {
            "value": 0.2,
            "unit": "px"
          },
          "paragraphSpacing": {
            "value": 0,
            "unit": "px"
          },
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": "none",
          "textIndent": {
            "value": 0,
            "unit": "px"
          },
          "textTransform": "none"
        }
      }
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.specifyapp.com/reference/parsers/convert-dimension.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.