# Migrating to 1.0

> Every renamed attribute, unit change and new default between motion-components 0.x and 1.0, with how to convert each one.

Source: https://www.motion-components.dev/docs/migration/

Version 1.0 makes the attributes consistent across all 40 components. Most changes are renames. A few change the unit, so the number changes too. The table below lists every change and how to convert it.

Upgrading from 1.0 or 1.1? Read the first section: since 1.2.0, every CSS custom property starts with `--mc-`.

## CSS custom properties start with --mc-

Since version 1.2.0, every CSS custom property starts with `--mc-`. The names without the prefix no longer work. Add `mc-` after the two dashes and keep the rest of the name:

```css
motion-icon {
  --mc-icon-color: #2563eb; /* was --icon-color */
}

motion-chart {
  --mc-chart-1: #e11d48; /* was --chart-1 */
}
```

| Component | Before | Now |
| --- | --- | --- |
| `motion-chart``motion-pie` | `--chart-height``--chart-surface``--chart-1``--chart-2``--chart-3``--chart-4``--chart-5``--chart-6``--chart-7``--chart-8` | `--mc-chart-height``--mc-chart-surface``--mc-chart-1``--mc-chart-2``--mc-chart-3``--mc-chart-4``--mc-chart-5``--mc-chart-6``--mc-chart-7``--mc-chart-8` |
| `motion-sparkline` | `--sparkline-width``--sparkline-height``--sparkline-color``--sparkline-accent` | `--mc-sparkline-width``--mc-sparkline-height``--mc-sparkline-color``--mc-sparkline-accent` |
| `motion-code` | `--code-keyword``--code-string``--code-tag``--code-attr``--code-num``--code-comment` | `--mc-code-keyword``--mc-code-string``--mc-code-tag``--mc-code-attr``--mc-code-num``--mc-code-comment` |
| `motion-countdown` | `--countdown-size``--countdown-color``--countdown-gap``--countdown-label-size``--countdown-label-color` | `--mc-countdown-size``--mc-countdown-color``--mc-countdown-gap``--mc-countdown-label-size``--mc-countdown-label-color` |
| `motion-dialog` | `--dialog-bg``--dialog-color``--dialog-radius``--dialog-padding``--dialog-max-width``--dialog-max-height``--dialog-shadow``--dialog-backdrop-color``--dialog-backdrop-blur` | `--mc-dialog-bg``--mc-dialog-color``--mc-dialog-radius``--mc-dialog-padding``--mc-dialog-max-width``--mc-dialog-max-height``--mc-dialog-shadow``--mc-dialog-backdrop-color``--mc-dialog-backdrop-blur` |
| `motion-icon``motion-icon-state` | `--icon-size``--icon-color``--icon-fill``--icon-accent` | `--mc-icon-size``--mc-icon-color``--mc-icon-fill``--mc-icon-accent` |
| `motion-progress` | `--progress-color` | `--mc-progress-color` |
| `motion-spotlight` | `--spotlight-color` | `--mc-spotlight-color` |
| `motion-theme-icon``motion-theme-toggle` | `--theme-icon-size``--theme-toggle-surface``--theme-toggle-border``--theme-toggle-accent``--theme-toggle-menu-bg``--theme-toggle-radius` | `--mc-theme-icon-size``--mc-theme-toggle-surface``--mc-theme-toggle-border``--mc-theme-toggle-accent``--mc-theme-toggle-menu-bg``--mc-theme-toggle-radius` |
| `motion-scene (set for its children)` | `--progress` | `--mc-progress` |
| `Theme colors``read by motion-code``motion-code-inline``motion-dialog``motion-image-compare``motion-progress``motion-ring and motion-slider` | `--color-accent``--color-accent-dim``--color-border``--color-muted``--color-surface``--color-surface-2``--color-text` | `--mc-color-accent``--mc-color-accent-dim``--mc-color-border``--mc-color-muted``--mc-color-surface``--mc-color-surface-2``--mc-color-text` |

This search lists the old names in your code. It also finds your own variables with the same names, so review each match:

```terminal
grep -rnE -- '--(color-|icon-|chart-|sparkline-|code-|countdown-|dialog-|progress|spotlight-|theme-)' src
```

## Install

```terminal
npm install motion-components@^1.0.0
```

## The rules in 1.0

| Rule | What it means for you |
| --- | --- |
| Time is in seconds | `duration`, `delay`, `interval` and `hold` are always seconds. Values that were milliseconds must be divided by 1000. |
| `interval` | Seconds between steps: characters, words or bursts. |
| `speed` | Only a rate per second: pixels per second (`motion-ticker`, `loop-speed`) or characters per second (`typing-speed`). |
| Springs | Every spring is tuned with `duration` and `bounce`. |
| Boolean attributes | Every boolean accepts `"false"`. Flags that are on by default, like `once`, `pin` or `labels`, can now be turned off in HTML: `once="false"`. |
| Triggers | `'view'` means when it scrolls into view and `'mount'` means once on load. `'hover'`, `'click'`, `'loop'` and `'scroll'` keep their meaning. |
| Events | Events start with `motion-`. The theme toggle keeps `colorschemechange` and `permanentcolorschemechange` for compatibility with `dark-mode-toggle`. |
| CSS custom properties | Start with `--mc-` and are named after the component: `--mc-dialog-*`, `--mc-countdown-*`, `--mc-code-*`, `--mc-progress-color`, `--mc-spotlight-color`. |

## Every change

| Component | 0.x | 1.0 | How to convert |
| --- | --- | --- | --- |
| `motion-arc` | `speed` | `duration` | Same number. Seconds per full rotation, `0` means no rotation. |
| `motion-blur` | `blur` | `intensity` | Same number, in pixels. |
| `motion-blur-in` | `blur` | `intensity` | Same number, in pixels. |
| `motion-circle` | `speed` | `duration` | Same number. Seconds per full rotation. |
| `motion-code` | `type` | `typing` | Boolean, same meaning. |
| `motion-code` | `type-speed` | `typing-speed` | Same number, characters per second. |
| `motion-code` | `type-delay` | `typing-delay` | Divide by 1000. Now in seconds. |
| `motion-code` | `type-loop-delay` | `typing-hold` | Divide by 1000. Now in seconds. |
| `motion-code` | `no-loop` | `typing-loop="false"` | Looping is on by default. Set `typing-loop="false"` to type once. |
| `motion-curve` | `speed` | `wave-duration` | Use `1 / speed`. Seconds per wave cycle, so `speed="0.4"` becomes `wave-duration="2.5"`. |
| `motion-font` | `trigger="auto"` | `trigger="view"` | Same behavior: animates when it scrolls into view. |
| `motion-glitch` | `interval` | `interval` | Divide by 1000. Now in seconds, so `2000` becomes `2`. |
| `motion-glitch` | `trigger="auto"` | `trigger="mount"` | Same behavior: glitches once on load. |
| `motion-gravity` | `stagger` | `interval` | Same number, seconds between characters. |
| `motion-gravity` | `fixed spring` | `duration, bounce` | `duration` now takes effect. `bounce` (default `0.45`) tunes the landing. |
| `motion-liquid` | `speed` | `duration` | Use `9 / speed`. Seconds per distortion cycle, so `speed="2"` becomes `duration="4.5"`. |
| `motion-parallax` | `speed` | `depth` | Same number. |
| `motion-perspective` | `animate` | `loop` | Boolean, same meaning. `loop` is the name; `oscillate` still works as an alias. |
| `motion-perspective` | `speed` | `duration` | Use `1 / speed`. Seconds per cycle, so `speed="1.5"` becomes `duration="0.667"`. |
| `motion-progress` | `color` | `--mc-progress-color` | Now a CSS custom property: `style="--mc-progress-color: #60a5fa"`. |
| `motion-scramble` | `speed` | `interval` | Divide by 1000. Seconds between glyph swaps. |
| `motion-scramble` | `delay` | `delay` | Divide by 1000. Now in seconds. |
| `motion-scramble` | `hover` | `trigger="hover"` | `trigger` is `'view'` (default) or `'hover'`. |
| `motion-slider` | `slidechange event` | `motion-change event` | Same `detail: { index }`. Now also composed. |
| `motion-spotlight` | `color` | `--mc-spotlight-color` | Now a CSS custom property: `style="--mc-spotlight-color: rgba(96,165,250,0.25)"`. |
| `motion-spotlight` | `smoothing, fade-duration` | `duration, bounce` | The follow is now a spring. `duration` sets both the follow and the fade. |
| `motion-stretch` | `stiffness, damping` | `duration, bounce` | `bounce` is `1 - damping / (2 × √stiffness)`, and `duration` is how long the old spring took to settle. Since 1.2.0 the defaults are `duration="0.77" bounce="0.55"`, the same spring as the old defaults `320` and `16`. `stiffness="400" damping="10"` is `duration="1.11" bounce="0.75"`. |
| `motion-swap` | `stagger-duration` | `interval` | Same number, seconds between characters. |
| `motion-swap` | `transition (property)` | `duration, bounce` | The old default `{ type: 'spring', duration: 0.7 }` is `duration="0.7" bounce="0.3"`. |
| `motion-swap` | `trigger="reveal"` | `trigger="view"` | Same behavior: swaps once when scrolled into view. |
| `motion-theme-toggle` | `transition="wipe"` | `wipe` | The page wipe is now off by default. Add the boolean `wipe` to turn it on. `transition="none"` can be removed. |
| `motion-typewriter` | `speed` | `interval` | Divide by 1000. Seconds between characters. |
| `motion-typewriter` | `delay` | `delay` | Divide by 1000. Now in seconds. |
| `motion-typewriter` | `pause` | `hold` | Divide by 1000. Seconds to hold the line before erasing. |
| `motion-words` | `interval` | `interval` | Divide by 1000. Now in seconds, so `2000` becomes `2`. |

## Code token colors

`motion-code` token colors move from `--cw-*` to `--mc-code-*`. Replace the prefix and keep the rest of the name:

```css
motion-code {
  --mc-code-keyword: #c678dd; /* was --cw-keyword */
  --mc-code-string: #98c379;  /* was --cw-string */
}
```

## New in 1.0

- `motion-press` and `motion-magnetic` have a `bounce` attribute. `motion-tilt` has `duration` and `bounce`.
- `motion-theme-toggle` has `icon-only` for the `toggle` appearance.
- Registering a component twice no longer throws. Two bundles can include the same component.
- Importing the library during server-side rendering no longer throws, so it works in Next.js, Astro and similar frameworks.
- `once="false"` replays the animation every time the element scrolls into view.
- Text components escape their text. Markup inside the text is shown as text and never runs as HTML.
- Screen readers read the whole text once in `motion-arc`, `motion-circle`, `motion-curve`, `motion-gravity` and `motion-perspective`, instead of letter by letter.
- With reduced motion, `motion-split` and `motion-headline` show their text at once.

## Find old attributes in your code

This search lists most of the attributes that changed. Review each match with the table above.

```terminal
grep -rnE 'speed=|stiffness=|damping=|stagger-duration=|type-speed=|type-delay=|type-loop-delay=|no-loop|smoothing=|fade-duration=|slidechange|--cw-|trigger="(auto|reveal)"' src
```