A super
media-query
for styled-component. Intuitive and easy of use.
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.
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
!
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.
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?
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!'
`}
`
This package follows the css3 media query
rule, click here to check it out.
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
Type | How to Use | Size | Comes after of | Following options | Can set css after? |
---|---|---|---|---|---|
xs | .xs |
0px | Media Feature |
Logical Operator |
β |
sm | .sm |
576px | Media Feature |
Logical Operator |
β |
md | .md |
768px | Media Feature |
Logical Operator |
β |
lg | .lg |
992px | Media Feature |
Logical Operator |
β |
xl | .xl |
1200px | Media Feature |
Logical Operator |
β |
Type | How to Use | Comes after of | Following options | Can set css after? |
---|---|---|---|---|
all | .all |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
aural | .aural |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
braille | .braille |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
handheld | .handheld |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
.print |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β | |
projection | .projection |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
screen | .screen |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
tty | .tty |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
tv | .tv |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
embossed | .embossed |
SuperQuery() , Logical Operator |
Logical Operator , Media Feature |
β |
Type | How to Use | Optional Argument Example | Comes after of | Following options | Can set css after? |
---|---|---|---|---|---|
width | .width |
.width.of('100px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-width | .minWidth |
.minWidth.of('100px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-width | .maxWidth |
.maxWidth.of('100px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
height | .height |
.height.of('340px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-height | .minHeight |
.minHeight.of('340px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-height | .maxHeight |
.maxHeight.of('340px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
device-width | .deviceWidth |
.deviceWidth.of('960px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-device-width | .minDeviceWidth |
.minDeviceWidth.of('960px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-device-width | .maxDeviceWidth |
.maxDeviceWidth.of('960px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
device-height | .height |
.height.of('320px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-device-height | .minDeviceHeight |
.minDeviceHeight.of('340px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-device-height | .maxDeviceHeight |
.maxDeviceHeight.of('340px') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
aspect-ratio | .aspectRatio |
.aspectRatio.of('1/1') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-aspect-ratio | .minAspectRatio |
.minAspectRatio.of('1/1') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-aspect-ratio | .maxAspectRatio |
.maxAspectRatio.of('1/1') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
device-aspect-ratio | .deviceAspectRatio |
.deviceAspectRatio.of('16/9') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-device-aspect-ratio | .minDeviceAspectRatio |
.minDeviceAspectRatio.of('16/9') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-device-aspect-ratio | .maxDeviceAspectRatio |
.maxDeviceAspectRatio.of('16/9') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
color | .color |
n/a |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-color | .minColor |
.minColor.of('4') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-color | .maxColor |
.maxColor.of('4') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
color-index | .colorIndex |
.colorIndex.of('256') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-color-index | .minColorIndex |
.minColorIndex.of('256') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-color-index | .maxColorIndex |
.maxColorIndex.of('256') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
monochrome | .monochrome |
n/a |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-monochrome | .minMonochrome |
.minMonochrome.of('8') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-monochrome | .maxMonochrome |
.maxMonochrome.of('8') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
resolution | .resolution |
.resolution.of('300dpi') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
min-resolution | .minResolution |
.minResolution.of('300dpi') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
max-resolution | .maxResolution |
.maxResolution.of('300dpi') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
scan | .scan |
.scan.of('progressive') |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
grid | .grid |
n/a |
SuperQuery() , Logical Operator , Media Type |
Logical Operator , Breakpoints |
β |
Type | How to Use | Comes after of | Following options | Can set css after? |
---|---|---|---|---|
landscape | .landscape |
Logical Operator |
Logical Operator |
β |
portrait | .portrait |
Logical Operator |
Logical Operator |
β |
Type | How to Use | Comes after of | Following options | Can set css after? |
---|---|---|---|---|
and | .and |
Media Feature , Screen Orientation , Breakpoints |
Media Type , Media Feature , Screen Orientation |
β |
or | .or |
Media Feature , Screen Orientation , Breakpoints |
Media Type , Media Feature , Screen Orientation |
β |
not | .not |
SuperQuery() |
Media Type |
β |
only | .only |
SuperQuery() |
Media Type |
β |
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;
`
`
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;
`};
`;
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);
- 3.0.0
SuperQuery
was rebuilt in order to improve its syntax and readability.- REMOVED:
configureBreakpoints()
to set custom breakpoints, useSuperQuery(myCustombreakpoints)
instead - NEW: No more
parentheses
! NowSuperQuery
has a fluid and human likely style.- Before:
SuperQuery().all().and().maxWidth().md().css...
- Now:
SuperQuery().all.and.maxWidth.md.css...
- Before:
- NEW:
.of(value)
method is introduced for all the cases you need to declare a value.- E.g.
SperQuery().minWidth.of('300px').css...
- E.g.
Server Side Render
tested.
- 2.0.0
- NEW: Option to override
bult-in breakpoints
directly fromSuperQuery(myCustombreakpoints)
- DEPRECATED:
configureBreakpoints()
to set custom breakpoints, useSuperQuery(myCustombreakpoints)
instead
- NEW: Option to override
- 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
- Fixed typo in the
- 0.1.0
- First release
- NEW: Created
configureBreakpoints()
to set custom breakpoints
- 0.0.1
- Work in progress
Marcos GonΓ§alves β LinkedIn β Website
Distributed under the MIT license. Click here for more information.
https://github.com/themgoncalves/super-query
- Fork it (https://github.com/themgoncalves/super-query/fork)
- Create your feature branch (
git checkout -b feature/fooBar
) - Commit your changes (
git commit -m ':zap: Add some fooBar'
) - Push to the branch (
git push origin feature/fooBar
) - Create a new Pull Request