Margin

Utilities for controlling an element's margin.

Add margin to a single side

Control the margin on one side of an element using the m{t|r|b|l}={space} utilities.

For example, mt={6} would add 1.5rem of margin to the top of an element, mr={4} would add 1rem of margin to the right of an element, mb={8} would add 2rem of margin to the bottom of an element, and ml={2} would add 0.5rem of margin to the left of an element.

<x.div mt={6}>mt=6</x.div>
<x.div mr={4}>mr=4</x.div>
<x.div mb={8}>mb=8</x.div>
<x.div ml={2}>ml=2</x.div>

Add horizontal margin

Control the horizontal margin of an element using the mx={size} utilities.

<x.div mx={8}>mx=8</x.div>

Add vertical margin

Control the vertical margin of an element using the my={size} utilities.

<x.div my={8}>my=8</x.div>

Add margin to all sides

Control the margin on all sides of an element using the m={size} utilities.

<x.div m={8}>m=8</x.div>

Negative margins

It is possible to specify a negative margin in all margin utilities.

<x.div w={32} h={16} bg="light-blue-300" />
<x.div mt={-8} bg="light-blue-600">
  mt=-8
</x.div>

Responsive

To control the margin of an element at a specific breakpoint, use responsive object notation. For example, adding the property my={{ md: 8 }} to an element would apply the my={8} utility at medium screen sizes and above.

<x.div my={{ md: 8 }} />

For more information about xstyled's responsive design features, check out Responsive Design documentation.

Customizing

Spacing scale

If you'd like to customize your values for margin, padding, space between, all at once, use the theme.space section of your theme.

  // theme.js
  export const theme = {
    space: {
+     sm: '8px',
+     md: '16px',
+     lg: '24px',
+     xl: '48px',
    },
  }

Learn more about customizing the default theme in the theme customization documentation.

If you don't want to customize it, a set of space is already defined in default theme:

const defaultTheme = {
  // ...
  space: {
    0.5: '0.125rem',
    1: '0.25rem',
    1.5: '0.375rem',
    2: '0.5rem',
    2.5: '0.625rem',
    3: '0.75rem',
    3.5: '0.875rem',
    4: '1rem',
    5: '1.25rem',
    6: '1.5rem',
    7: '1.75rem',
    8: '2rem',
    9: '2.25rem',
    10: '2.5rem',
    11: '2.75rem',
    12: '3rem',
    14: '3.5rem',
    16: '4rem',
    20: '5rem',
    24: '6rem',
    28: '7rem',
    32: '8rem',
    36: '9rem',
    40: '10rem',
    44: '11rem',
    48: '12rem',
    52: '13rem',
    56: '14rem',
    60: '15rem',
    64: '16rem',
    72: '18rem',
    80: '20rem',
    96: '24rem',
  },
}

Styled bindings

Automatic

Using xstyled's styled, all spacing scales defined are automatically bound to all margins, paddings and gap attributes:

import styled from '@xstyled/...'

const Card = styled.button`
  margin: 3;
`

To learn more about styled syntax, read styled syntax documentation.

Manual

It is possible to manually bind a spacing scale using th.space utility:

import styled from '...'
import { th } from '@xstyled/...'

const Card = styled.button`
  margin: calc(2px + ${th.space(3)});
`

Hooks

Get a spacing scale in any component using useSpace hook:

import { useSpace } from '@xstyled/...'

function Card() {
  const space = useSpace(3)
}