styled-query-builder

A semantic tool to help you build responsive interfaces with Styled Components

Usage no npm install needed!

<script type="module">
  import styledQueryBuilder from 'https://cdn.skypack.dev/styled-query-builder';
</script>

README

logo

GitHub Workflow Status Codecov npm bundle size Dependencies NPM

styled-query-builder 🔨

Sometimes, working with media queries isn't easy. It's hard to remember what "min-width" or "max-width" stand for, if the styles will be applied if the screen is smaller or bigger than the specified. This is what styled-query-builder aims to solve. With this tool, you can write media queries in a semantic way.

styled-query-builder is a library made to work alongside styled-components.

Why use it?

It is easy to use, well-documented and tested!

Features

Getting Started

Pre-requisites

You need to be on a project that has styled-components as a dependency.

Installation

You can install styled-query-builder with npm

npm install styled-query-builder

or with yarn

yarn add styled-query-builder

Usage

This library has, as default, the following breakpoints:


breakpoints

and "px" as size unit.

Disclaimer

  1. If you want to use "rem" as size unit, you will have to use the "builder()" method.
  2. If you want to call the methods as in:

below function

but want different breakpoints, you will also have to use the "builder()" method. Otherwise, if you want to use different breakpoints, but don't care about calling the methods as above, you can call them as in:


below function

API

above(size, antiOverlap?)

This function applies the style if the screen is bigger than the informed size. It is equivalent to "@media (min-width: ...)".


above function

below(size, antiOverlap?)

This function applies the style if the screen is smaller than the informed size. It is equivalent to "@media (max-width: ...)".


below function

between(sizes)

This function applies the style if the screen size is between the informed sizes. It is equivalent to "@media (min-width: ...) and (max-width: ...)".


between function

breakpoints(mediaQueryType, sizes, antiOverlap?)

This function returns the media query that the user wants. It is perfect to mock a size screen in tests that uses jest-styled-components, and a lot more.


breakpoints function

builder(userBreakpoints, sizeUnit)

This function is for who wants custom breakpoints or use "rem" as size unit. You load it with the breakpoints and the size unit, and it returns all the above methods to you: "above()", "below()", "between()" and "breakpoints()".


builder function

Functions Parameters

antiOverlap?

If, somehow, you use two media queries that "bump" each other, like:


below function

You can use this property to solve this issue. If you are calling the "below()" method, it will reduce from the media query the value that you pass. If you are calling the "above()" method, it will add to the media query the value that you pass.


below function

mediaQueryType

It can be the following values: "above", "below" or "between".

size

It can be one of the keys of the breakpoints (the default ones or the ones provided by the user), or a value indicating a size.

sizes

It can be a size or a size array with two values.

sizeUnit

It can be the following values: "px" or "rem".

userBreakpoints

It can be an object like the default breakpoints, with how many breakpoints the user wants.

Examples

This README file has only simple examples. If you want more, take a look at the examples folder and run them by yourself.

Basic step:

git clone https://github.com/MathewsMachado/styled-query-builder.git && \
cd styled-query-builder && \
yarn

  • To run the above example: cd docs/examples/above && yarn && yarn start

  • To run the antiOverlap example: cd docs/examples/antiOverlap && yarn && yarn start

  • To run the below example: cd docs/examples/below && yarn && yarn start

  • To run the between example: cd docs/examples/between && yarn && yarn start

  • To run the breakpoints example: cd docs/examples/breakpoints && yarn && yarn start

  • To run the builder example: cd docs/examples/builder && yarn && yarn start

To-Do

  • Improve regex at "hasLettersAndNumbers".

  • Docs: Fix the Eslint error that only allows the examples to run if there are the node_modules folder in the root directory.

  • Tests: Look for general improvements.

  • Typing: Improve typing. Now, there are no code completion and no syntax highlight due to it.

  • Typing: Integrate better with styled-components.

  • Typing: Fix the errors across the codebase, which are marked as "// typescript issue". The items 2, 3 and 4 below are related and on the same file.

    1. on mediaQueryTypeMapper
    2. on mediaQuery tests
    3. on mediaQuery tests
    4. on mediaQuery tests

Contribution

This project is accepting contributions, the aim is to clean the to-do list. We are really needing help with typing.

Feel free to open an issue or submit a pull request. In the case of a pull request, explain well what you are doing and create tests for it.

Acknowledgement

This project was inspired by Morajabi's library, styled-media-query.

I want to thanks Willian Machado for having done the library logo and proofreading this README.

License

This project is licensed under the MIT License - see the LICENSE file for details.