Introduction

Sass function & mixin to convert pixel to rem.

Note: this code has been moved to @unsass/rem new package, use this one for better support.

Installing

npm install @sass-collective/rem

Usage

@use "@sass-collective/rem";

.foo {
    font-size: rem.convert(16px);
}

Configuration

@use "@sass-collective/rem" with (
    $baseline: 10px
);

Options

| Variable | Default | Description | |-------------|---------|----------------------------------| | $baseline | 16px | Sets baseline reference in px. |

Top-level config override

If variables are already configured on top-level using @use ... with, by another dependency for example, you can't use this solution anymore, because the module can only be setup once, this is a Sass restriction with Module System, but another solution exist for override the main configuration, with a mixin!

See official documentation about override configuration with mixins.

| Mixin | Description | |---------------------|:-----------------------------------------| | config($baseline) | Override top-level with configuration. |

Configuration rule with rem.config()

The following Sass will configure new parameters:

@use "@sass-collective/rem";

@include rem.config(10px);
// variables.$baseline: 10px;

API

Sass functions

| Function | Description | |-------------------------|-----------------------------------------------------------------------------| | baseline($percentage) | Sets root baseline value with default $percentage at 100%. | | convert($values...) | Convert px unit to rem. | | rem($values...) | Fallback name of convert() function. See "Fallback" section. |

Baseline with rem.baseline()

The following Sass...

@use "@sass-collective/rem";

html,
body {
    font-size: rem.baseline();
}

...will produce the following CSS...

html,
body {
    font-size: 100%
}

Convert with rem.convert()

The following Sass...

@use "@sass-collective/rem";

.foo {
    font-size: rem.convert(16px); // Single value.
    margin: rem.convert(20px 30px); // Multiple values.
    border: rem.convert(1px solid darkcyan); // Multiple mixed values.
    box-shadow: rem.convert(0 0 10px 5px rgba(darkcyan, 0.75), inset 0 0 10px 5px rgba(darkcyan, 0.75)); // Comma-separated values.
}

...will produce the following CSS...

.foo {
    font-size: 1rem;
    margin: 1.25rem 1.875rem;
    border: 0.0625rem solid darkcyan;
    box-shadow: 0 0 0.625rem 0.3125rem rgba(0, 139, 139, 0.75), inset 0 0 0.625rem 0.3125rem rgba(0, 139, 139, 0.75);
}

Sass mixins

| Mixin | Description | |----------------------------------------------|-------------------------------------------------------------------------------------| | baseline | Sets declaration with font-size property. | | declaration($property, $value, $important) | Sets declaration with conversion of px unit to rem, with optional !important. | | rem($property, $value, $important) | Fallback name to convert() mixin. See "Fallback" section. |

Baseline declaration with rem.baseline()

The following Sass...

@use "@sass-collective/rem";

html,
body {
    @include rem.baseline;
}

...will produce the following CSS...

html,
body {
    font-size: 100%
}

Convert declaration with rem.declaration()

The following Sass...

@use "@sass-collective/rem";

.foo {
    @include rem.declaration(font-size, 16px); // Single value.
    @include rem.declaration(margin, 20px 30px); // Multiple values.
    @include rem.declaration(border, 1px solid darkcyan); // Multiple mixed values.
    @include rem.declaration(box-shadow, 0 0 10px 5px rgba(darkcyan, 0.75), inset 0 0 10px 5px rgba(darkcyan, 0.75)); // Comma-separated values.
}

...will produce the following CSS...

.foo {
    font-size: 1rem;
    margin: 1.25rem 1.875rem;
    border: 0.0625rem solid darkcyan;
    box-shadow: 0 0 0.625rem 0.3125rem rgba(0, 139, 139, 0.75), inset 0 0 0.625rem 0.3125rem rgba(0, 139, 139, 0.75);
}

Fallback

You can use the fallback name if your namespace is not enough explicit for what ever reason...

@use "@sass-collective/rem" as foo;

.foo {
    font-size: foo.rem(16px);
}

.bar {
    @include foo.rem(font-size, 16px);
}

...or use more globally namespace... (beware of conflicts with others modules)

@use "@sass-collective/rem" as *;

.foo {
    font-size: rem(16px);
}

.bar {
    @include rem(font-size, 16px);
}