CSS transition-duration Property

This property defines how many seconds or milliseconds a transition effect takes to complete its journey from the start state to the end state.

selector { transition-duration: 0.3s; }

<time>	Specifies the length of time a transition animation takes to complete using seconds (s) or milliseconds (ms).
0s	The default value that causes the property change to happen instantaneously.

Code Examples

A basic hover effect where the background color and width transition smoothly over half a second.

<style>
.simple-box {
  width: 100px;
  height: 100px;
  background-color: #ff5722;
  transition-property: background-color, width;
  transition-duration: 0.5s;
}
.simple-box:hover {
  background-color: #ffeb3b;
  width: 200px;
}
</style>
<div class="simple-box"></div>

An advanced example using JavaScript to dynamically override the CSS duration before toggling a class that triggers the transition.

<style>
.panel {
  width: 200px;
  height: 200px;
  background-color: #2196f3;
  opacity: 1;
  transition-property: opacity, transform;
  transition-duration: 300ms;
}
.fade-out {
  opacity: 0;
  transform: scale(0.5);
}
</style>
<div id="ui-panel" class="panel"></div>
<button onclick="togglePanel()">Toggle Panel</button>
<script>
function togglePanel() {
  const panel = document.getElementById("ui-panel");
  // Dynamically changing duration based on application state
  panel.style.transitionDuration = "1000ms";
  panel.classList.toggle("fade-out");
}
</script>

Pro Tip

You can create complex multi-stage feels by assigning different durations to different properties on the same element. For example, you can make a card expand its width quickly (0.2s) while fading in its text content more slowly (0.8s) to create a more sophisticated, professional visual flow.

Deep Dive

Think of transition-duration as the speed limit for a state change. Without it, an element teleports instantly from one style to another. When you set a duration, you are commanding the browser to calculate and render all the intermediate frames between the starting style and the ending style. If you change an element's width from 100px to 200px with a duration of 1s, the browser paints the growth incrementally over that second. It works in tandem with transition-property. If you provide multiple durations separated by commas, they map to the properties listed in the transition-property declaration in the same order. If fewer durations are provided than properties, the list of durations is repeated.

Best Practices

Keep your UI snappy. For most interactive elements like buttons or menu links, a duration between 200ms and 400ms is the sweet spot. Anything longer than 500ms often makes the interface feel sluggish or 'heavy' to the user. Use milliseconds (ms) for fine-grained control over fast interactions and seconds (s) for longer, decorative background animations.

Common Pitfalls

The biggest mistake is forgetting the unit. In CSS, writing transition-duration: 500; does nothing because the browser doesn't assume you mean milliseconds; it must be 500ms. Also, remember that a duration of 0s is the default, so if you don't see your transition working, check if you actually defined a duration or if it's being overridden by a shorthand property elsewhere in your stylesheet.

Accessibility

Some users are sensitive to motion and can experience nausea or dizziness from large sliding or scaling transitions. Always wrap your non-essential transitions in a media query that checks for prefers-reduced-motion: reduce. This allows users with motion sensitivities to navigate your site comfortably by disabling the animations.

Dev Data Table: transition-duration property

default	0s
animatable	no
inherited	no
experimental	no
year_intro	2009
year_standard	2013
js_syntax_1	object.style.transitionDuration = "0.5s";
js_syntax_2	object.style.setProperty("transition-duration", "500ms");
js_note	When using JavaScript to set this value, always include the unit suffix like "s" or "ms" within the string.
browsers	{ "Chrome": 26, "Edge": 12, "Firefox": 16, "Safari": 9, "Opera": 15, "Chrome Android": 26, "Safari on iOS": 9, "Samsung Internet": 1, "Opera Mobile": 15 }