Rupture is a utility for working with media queries in stylus. It takes advantage of stylus' new block mixins to provide useful helpers that make breakpoints much more clear to read and simple to code. Rupture is based loosely on breakpoint-slicer, a sass plugin with similar functionality.
You can install use rupture through npm, as such:
npm install rupture
...and you can use it in any way that stylus plugins are normally used. An example is shown below with accord, a simple interface to many different compiled js languages.
var accord = require('accord'),
stylus = accord.load('stylus'),
rupture = require('rupture');
stylus.renderFile('example.styl', { use: rupture() })
.done(console.log.bind(console), console.error.bind(console))
All functions provided by rupture are block mixins, meaning that they should be called prefixed with a +. You can use any of the mixins either with pixel/em values or with scale values. Let's review the scale first so that it's easy to understand.
Rupture provides a variable called scale. Below is the default value, but you are welcome to overwrite this with anything else you want:
scale = 0 400px 600px 800px 1050px
The scale variables can also have as many values as you'd like, so don't feel limited to the number in the default value. Now, imagine that the variables listed here represent a scale on your site, with each slice having a number, as such:
Breakpoint: 0 400px 600px 800px 1050px
├───────────────────┼─────────┼─────────┼───────────┼─────────>
Slice #: 0 1 2 3 4
As mentioned above, you can have as many slices as you want, they just count up from the first one at index zero. So that's the scale. Now let's move on to the mixins.
So there are two “categories” of mixins that are a part of rupture. The first is a very basic set designed to simply shorten and sweeten standard media queries, and the second is a very close port of the fantastic breakpoint-slicer library, which can be used almost as a grid. We'll go through these in order.
+above(measure)When the screen size is above the provided measure, the styles in the block will take effect.
+from-width(measure)Alias of above. Styles take effect from the provided measure and above.
+below(measure)When the screen size is below the provided measure, the styles in the block will take effect.
+to-width(measure)Alias of below. Styles take effect from zero up to the provided measure.
+between(measure, measure)When the screen size is between the two provided measure, the styles in the block will take effect.
+at(measure)Intended for use with scale measures, when the screen size is between the provided scale measure and the one below it, the styles in the block will take effect. For example, if your scale was something like scale = 0 400px 600px, and you used the mixin like +at(2), it would kick in between 400 and 600px (remember, scale is zero indexed, so 2 is the third value, and one less is the second). If you use this with a value, it will not have much effect, as it will be at one specific pixel value rather than a range like you want.
+mobile()When the screen size is 400px (defined by mobile-cutoff) or less, the styles in the block will take effect.
+tablet()When the screen size is between 1050px (defined by desktop-cutoff) and 400px (defined by mobile-cutoff), the styles in the block will take effect.
+desktop()When the screen size is 1050px (defined by desktop-cutoff) or more, the styles in the block will take effect.
+retina()When the device has a pixel density of over 1.5 (retina), the styles in the block will take effect.
When I say “measure” in any of the docs above, this could mean either pixels (like 500px), ems (like 20em), or an index on the scale (like 2). Scale indices will be converted from the index to whatever the value is at that index in the scale variable. The scale starts at a zero-index.
If you need help with rupture, feel free to ask me on twitter. If you think you have found a problem with rupture or have an idea for a new feature, please file an issue on github.
Othwerwise, enjoy!