README.md

spacing-util

A simple library agnostic util functions for css-in-js styling solutions to make your design spacing consistent

Install

npm install spacing-util

Motivation

---

Not every single UI library has its own theme or if does it might lack of spacing system that might fit your needs.

spacing-util is built in customizable way to allow you create your own spacing system which can work even if your library doesn't allow rewriting/extending their theme.

 

Features

---

 

Spacing

Spacing usage is mentioned to be mainly used for padding and margin properties. That's why it's usage is similar to CSS syntax - you can pass up to 4 properties which will be calculated by parser function.

Passing argument different than number returns it without any transform.

Default parser function multiplies given argument by 4 and returns as px unit.

Example usage

import { spacing } from 'spacing-util';

spacing(1); // 4px
spacing(5); // 20px
spacing(5, 6); // 20px 24px
spacing(5, 2, 1); // 20px 8px 4px
spacing(5, 6, 1, 6); // 20px 24px 4px 24px

spacing(2, '5em'); // 8px 5em

As inline style

import { spacing } from 'spacing-util';

const RandomBox = () => (
  <div
    style={{
      padding: spacing(4, 8),
      borderRadius: spacing(1),
    }}
  >
    random box
  </div>
);

With emotion

import { spacing } from 'spacing-util';
import { css, cx } from '@emotion/css';

const RandomBox = () => (
    <div
    className={css`
      padding: ${spacing(4, 8)};
      border-radius: ${spacing(1)};
    `}
  >
    random box
  </div>

With styled-components

import { spacing } from 'spacing-util';
import styled from 'styled-components';

const StyledBox = styled.div`
  padding: ${spacing(8)};
  border-radius: ${spacing(1)};
`;

const RandomBox = () => <StyledBox>random box</StyledBox>;

 

Spacing generator

Sometimes the default parser function might not satisfy you or your design needs. That's why you can create your own spacing function.

You are not limited to just one spacing across the app. It's up to you what will be the names for your spacings :)

Usage

import { generateSpacing } from 'spacing-util';
import type { SpacingParser } from 'spacing-util';

// Default parser function
const parser: SpacingParser = value =>
  typeof value === 'number' ? `${~~(value * 4)}px` : value;

const spacing = generateSpacing(parser);

Padding and margin function

In case when you are lazy enough and feel bored of typing for example:

const StyledBox = styled.div`
  padding: ${spacing(8, 4)};
  margin: ${spacing(5)};
`;

There is a shorter way to do that by using padding and margin util functions.

Usage

import { padding, margin } from 'spacing-util';

const StyledBox = styled.div`
  ${padding(8, 4)}
  ${margin(5)}
`;

Both shares same usage as spacing function with 1 extra option. Instead number or string input, you can an object of type:

{
  x: number | string;
  y: number | string;
  top: number | string;
  right: number | string;
  bottom: number | string;
  left: number | string;
}

top, right, bottom, left are responsible for returning just for these specific direction meanwhile x, y are like a shortcut for left + right and top + bottom usage. Values given for given key later on are transformed with spacing parser function.

Note - if u will use x shorthand with left together, the order matters! The value at the bottom will ovveride the previous one - behavior just like in vanilla CSS

Examples

padding({
  x: 4,
  top: 5,
});

// returns
// padding-top: 20px;
// padding-right: 20px;
// padding-left: 20px;

Padding and margin generator

Since margin and padding are built on top of spacing function and you enjoy it's usage you are able to create your own padding and margin utils by passing a parser function to it's generator function.

Usage

import { generateMargin, generatePadding } from 'spacing-util';
import type { SpacingParser } from 'spacing-util';

// Default parser function
const parser: SpacingParser = value =>
  typeof value === 'number' ? `${~~(value * 4)}px` : value;

const margin = generateMargin(parser);
const padding = generatePadding(parser);