sass-site/source/_includes/doc_snippets/number-units.liquid

{% markdown %}
  ## Units

  Sass has powerful support for manipulating units based on how [real-world unit
  calculations][] work. When two numbers are multiplied, their units are
  multiplied as well. When one number is divided by another, the result takes
  its numerator units from the first number and its denominator units from the
  second. A number can have any number of units in the numerator and/or
  denominator.

  [real-world unit calculations]: https://en.wikipedia.org/wiki/Unit_of_measurement#Calculations_with_units_of_measurement
{% endmarkdown %}

{% codeExample 'number-units', false %}
  @debug 4px * 6px; // 24px*px (read "square pixels")
  @debug math.div(5px, 2s); // 2.5px/s (read "pixels per second")

  // 3.125px*deg/s*em (read "pixel-degrees per second-em")
  @debug 5px * math.div(math.div(30deg, 2s), 24em);

  $degrees-per-second: math.div(20deg, 1s);
  @debug $degrees-per-second; // 20deg/s
  @debug math.div(1, $degrees-per-second); // 0.05s/deg
  ===
  @debug 4px * 6px  // 24px*px (read "square pixels")
  @debug math.div(5px, 2s)  // 2.5px/s (read "pixels per second")

  // 3.125px*deg/s*em (read "pixel-degrees per second-em")
  @debug 5px * math.div(math.div(30deg, 2s), 24em)

  $degrees-per-second: math.div(20deg, 1s)
  @debug $degrees-per-second  // 20deg/s
  @debug math.div(1, $degrees-per-second)  // 0.05s/deg
{% endcodeExample %}

{% headsUp %}
  Because CSS doesn't support complex units like square pixels, using a number
  with complex units as a [property value][] will produce an error. This is a
  feature in disguise, though; if you aren't ending up with the right unit, it
  usually means that something's wrong with your calculations! And remember, you
  can always use the [`@debug` rule][] to check out the units of any variable or
  [expression][].

  [property value]: /documentation/style-rules/declarations
  [`@debug` rule]: /documentation/at-rules/debug
  [expression]: /documentation/syntax/structure#expressions
{% endheadsUp %}

{% markdown %}
  Sass will automatically convert between compatible units, although which unit
  it will choose for the result depends on which implementation of Sass you're
  using. If you try to combine incompatible units, like `1in + 1em`, Sass will
  throw an error.
{% endmarkdown %}

{% codeExample 'compatible-units', false %}
  // CSS defines one inch as 96 pixels.
  @debug 1in + 6px; // 102px or 1.0625in

  @debug 1in + 1s;
  //     ^^^^^^^^
  // Error: Incompatible units s and in.
  ===
  // CSS defines one inch as 96 pixels.
  @debug 1in + 6px  // 102px or 1.0625in

  @debug 1in + 1s
  //     ^^^^^^^^
  // Error: Incompatible units s and in.
{% endcodeExample %}

{% markdown %}
  As in real-world unit calculations, if the numerator contains units that are
  compatible with units in the denominator (like `math.div(96px, 1in)`), they'll
  cancel out. This makes it easy to define a ratio that you can use for
  converting between units. In the example below, we set the desired speed to
  one second per 50 pixels, and then multiply that by the number of pixels the
  transition covers to get the time it should take.
{% endmarkdown %}

{% codeExample 'transition' %}
  @use 'sass:math';

  $transition-speed: math.div(1s, 50px);

  @mixin move($left-start, $left-stop) {
    position: absolute;
    left: $left-start;
    transition: left ($left-stop - $left-start) * $transition-speed;

    &:hover {
      left: $left-stop;
    }
  }

  .slider {
    @include move(10px, 120px);
  }
  ===
  @use 'sass:math'

  $transition-speed: math.div(1s, 50px)

  @mixin move($left-start, $left-stop)
    position: absolute
    left: $left-start
    transition: left ($left-stop - $left-start) * $transition-speed

    &:hover
      left: $left-stop



  .slider
    @include move(10px, 120px)
{% endcodeExample %}

{% headsUp %}
  If your arithmetic gives you the wrong unit, you probably need to check your
  math. You may be leaving off units for a quantity that should have them!
  Staying unit-clean allows Sass to give you helpful errors when something isn't
  right.

  You should especially avoid using interpolation like `#{$number}px`. This
  doesn't actually create a number! It creates an [unquoted string][] that
  *looks* like a number, but won't work with any [number operations][] or
  [functions][]. Try to make your math unit-clean so that `$number` already has
  the unit `px`, or write `$number * 1px`.

  [unquoted string]: /documentation/values/strings#unquoted
  [number operations]: /documentation/operators/numeric
  [functions]: /documentation/modules/math
{% endheadsUp %}

{% headsUp %}
  Percentages in Sass work just like every other unit. They are *not*
  interchangeable with decimals, because in CSS decimals and percentages mean
  different things. For example, `50%` is a number with `%` as its unit, and
  Sass considers it different than the number `0.5`.

  You can convert between decimals and percentages using unit arithmetic.
  `math.div($percentage, 100%)` will return the corresponding decimal, and
  `$decimal * 100%` will return the corresponding percentage. You can also use
  the [`math.percentage()` function][] as a more explicit way of writing
  `$decimal * 100%`.

  [`math.percentage()` function]: /documentation/modules/math#percentage
{% endheadsUp %}