@themgoncalves/super-query v3.0.0

🎠 Super-Query

A super media-query for styled-component. Intuitive and easy of use.

Description

We all know that Media Query is a very important part of your application; with that you can set any kind of responsiveness and device control.

Most of the developers only use simple media feature as part of the media query syntax, and for that simple use case, there's a bunch of good approach for your styled-component based application.

Media Feature examples: width | min-width | max-width | height | min-height | max-height

But how about control over the screen orientation, aspect-ratio, resolution and tv devices? Or even a interpolation between?

For those developers who need more control over the styled-component based application, we created the SuperQuery in order to provide a full powerful and simple control over your media query.

Want a simple code demonstration?

How about create a media query that handles screen widths between 360px and 1024px ?

const myStyledComponent = styled.div`
  ...
  ${SuperQuery().minWidth.of('360px').and.maxWidth.of('1024px').css`
    content: 'this is awesome!'
  `}
`

Cool, right? But it's even cooler to use our built-in breakpoints, let's rewrite it!

const myStyledComponent = styled.div`
  ...
  ${SperQuery().minWidth.sm.and.maxWidth.lg.css`
    content: 'this is even more awesome!'
  `}
`

Of even how about control the screen orientation over mobile devices ?

const myStyledComponent = styled.div`
  ...
  ${SuperQuery().maxWidth.md.and.landscape.css`
    content: 'Yep! Your device is on landscape mode!'
  `}
`

Want a more complex query ?

const myStyledComponent = styled.div`
  ...
  ${SuperQuery()
     .screen
     .and
     .deviceAspectRatio
     .of('16/9')
     .or
     .screen
     .and
     .deviceAspectRatio
     .of('16/10')
     .css`
    content: 'Yep! Your device is on landscape mode!'
  `}
`

Yeah! Now you know how simple and powerful is SuperQuery!

Installation

Since we have experience some issues with NPM along the time, we strongly recomment the use of YARN Package Manage;

Download our NPM Package

For YARN users:

yarn add @themgoncalves/super-query

For NPM users:

npm install @themgoncalves/super-query

Note that it should not be in the devDependencies.

How to use

First we need to import the package into our component;

import SuperQuery from '@themgoncalves/super-query';

Then, we are ready to mix it with styled-component:

const Title = styled.h1`
  color: #666;
  font-size: 16px;
  ${SuperQuery().minWidth.lg.css`
    font-size: 20px;
  `};
  ${SuperQuery().minWidth.lg.and.landscape.css`
    font-size: 26px;
  `};
`;

See how easy to implement it is?

Implementation TIP!

If you're using ThemeProvider from styled-components, it might be an excellent idea to place SuperQuery as member of you theme configuration, this will eliminate the need to import it every single time you need to use and also, you only need to customize your breakpoints once! 😜

// theme.js
import SuperQuery from '@themgoncalves/super-query';

const theme = {
    typography: {
        fonts: {
            roboto: "'Roboto', sans-serif",
        },
    },
    SuperQuery: SuperQuery(breakpoints),
};

export default theme;

And then, you can access it directly from the props.theme. E.g.

const myStyledComponent = styled.div`
  ...
  ${props.theme.SuperQuery.minWidth.sm.and.maxWidth.lg.css`
    content: 'this is even more awesome!'
  `}
`

API Documentation

This package follows the css3 media query rule, click here to check it out.

The Media Query Syntax

A few motivating and useful examples of how your product can be used. Spice this up with code blocks and potentially more screenshots.

media_query: [[only | not]? <media_type> [ and <expression> ]*] |
             <expression> [ and <expression> ]*

expression: ( <media_feature> [: <value>]? )

media_type: all | aural | braille | handheld | print |
  projection | screen | tty | tv | embossed

media_feature: width | min-width | max-width
  | height | min-height | max-height
  | device-width | min-device-width | max-device-width
  | device-height | min-device-height | max-device-height
  | aspect-ratio | min-aspect-ratio | max-aspect-ratio
  | device-aspect-ratio | min-device-aspect-ratio | max-device-aspect-ratio
  | color | min-color | max-color
  | color-index | min-color-index | max-color-index
  | monochrome | min-monochrome | max-monochrome
  | resolution | min-resolution | max-resolution
  | scan | grid

Built-in Breakpoints

Media Type

Media Feature

Screen Orientation

Logical Operator

Render CSS

Simply call the css function as the last iteration and pass the css syntax throw ES6 Tagged Template Literals:

const List = styled.ul`
  list-style: none;
  padding: 0;
  margin: 0;
  SuperQuery().minWidth.md.css`
    color: white;
    font-size: 14px;
    text-decoration: none;
  `
`

How to create custom breakpoints?

One of the coolest features we have on SuperQuery is the possibility to override our default breakpoints into your own custom.

Here is how to do:

import SuperQuery from '@themgoncalves/super-query';

// Here is an example of a custom breakpoint
const customBreakpoints = {
  extraSmall: 360,
  small: 640,
  medium: 960,
  large: 1024,
  extraLarge: 1200,
  superExtraLarge: 1600,
};

// Then just import your custom breakpoints into the `SuperQuery`
// and you are Zready start use it!
const Title = styled.h1`
  color: #666;
  font-size: 16px;
  ${SuperQuery(customBreakpoints).minWidth.superExtraLarge.css`
    font-size: 20px;
  `};
`;

// Or your custom breakpoints directly from `ThemeProvider`
const Title = styled.h1`
  color: #666;
  font-size: 16px;
  ${props => SuperQuery(props.theme.breakpoints).minWidth.superExtraLarge.css`
    font-size: 20px;
  `};
`;

Orientation

We have added since the version 1.0.0 a new feature: Orientation, which is a Screen Orientation manager.

This feature is an implementation of the Web API Screen.orientation available in the modern browser.

Note that this feature might not work on a several environments, like in the iOS. For more information, click here and check the browser compatibility

How to use

import { Orientation } from '@themgoncalves/super-query';

// or you can import direct the module

import Orientation from '@themgoncalves/super-query/orientation';

Listening for screen orientation change

Orientation.onChange((orientation) => {
    console.info('Screen orientation has changed to: ', orientation);
});

Get the current orientation

const currentOrientation = Orientation.current();
console.info('Current screen orientation: ', currentOrientation);

Locking the orientation

// screen orientations available to be locked:
// landscape-primary
// landscape-secondary
// portrait-primary
// portrait-secondary

const wasScreenLocked = Orientation.lock('portrait-primary');

// or you can pass an array with the orientations to be locked
const wasScreenLocked = Orientation.lock(['portrait-primary', 'portrait-secondary']);

console.info('Was screen locked? ', wasScreenLocked);

Unlocking the screen

const wasScreenUnlocked = Orientation.unlock();
console.info('Was screen unlocked? ', wasScreenUnlocked);

Check if the screen orientation was locked before

const wasScreenOrientationLocked = Orientation.isLocked();
console.info('Was screen orientation locked before? ', wasScreenOrientationLocked);

Release History

• 3.0.0
  • SuperQuery was rebuilt in order to improve its syntax and readability.
  • REMOVED: configureBreakpoints() to set custom breakpoints, use SuperQuery(myCustombreakpoints) instead
  • NEW: No more parentheses! Now SuperQuery has a fluid and human likely style.
    • Before: SuperQuery().all().and().maxWidth().md().css...
    • Now: SuperQuery().all.and.maxWidth.md.css...
  • NEW: .of(value) method is introduced for all the cases you need to declare a value.
    • E.g. SperQuery().minWidth.of('300px').css...
  • Server Side Render tested.
• 2.0.0
  • NEW: Option to override bult-in breakpoints directly from SuperQuery(myCustombreakpoints)
  • DEPRECATED: configureBreakpoints() to set custom breakpoints, use SuperQuery(myCustombreakpoints) instead
• 1.0.0
  • Stable version
  • NEW: Created Orientation - Screen Orientation management
  • NEW: Created Example (Demo) of Super-Query
  • Improved folder structure
• 0.1.1
  • Fixed typo in the ToString method used for tests
  • Minor fixes and improvement in the project's documentation
• 0.1.0
  • First release
  • NEW: Created configureBreakpoints() to set custom breakpoints
• 0.0.1
  • Work in progress

Meta

Author

Marcos Gonçalves – LinkedIn – Website

License

Distributed under the MIT license. Click here for more information.

https://github.com/themgoncalves/super-query

Contributing

1. Fork it (https://github.com/themgoncalves/super-query/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -m ':zap: Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request