CSS library for Instagram filters

Una Kravets

Last update: Jan 4, 2023

Related tags

Learning resource CSSgram

Overview

CSSgram

CSSGram is an Instagram filter library written in Sass and CSS.

What is This?

Simply put, CSSgram is a library for editing your images with Instagram-like filters directly using CSS. What we're doing is adding filters to the images, as well as applying color and/or gradient overlays via various blending techniques to mimic filter effects. This means less manual image processing and more fun filter effects on the web!

We're using pseudo-elements (i.e. ::before and ::after) to create the filter effects, so you must apply these filters on a containing element (i.e. not a replaced element like <img>). The recommendation is to wrap your images in a <figure> tag. More about the tag here.

Browser Support

This library uses CSS Filters and CSS Blend Modes. These features are supported in the following browsers:


43+ ✔	38+ ✔	Nope ✘	13 ✔	32+ ✔	8+ ✔

For more information, check on Can I Use.

Usage

There are currently 2 ways to consume this library:

Use CSS classes

When using CSS classes, you can simply add the class with the filter name to the element containing your image.

Include the CDN link in your <head> tag: <link rel="stylesheet" href="https://cssgram-cssgram.netdna-ssl.com/cssgram.min.css">. We're also on CDNJS which means another option is <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/cssgram/0.1.10/cssgram.min.css">

Alternatively, you can download the CSSgram library locally and link to the it within your project: <link rel="stylesheet" href="css/vendor/cssgram.min.css">
Add a class to your image element with the name of the filter you would like to use

For example:

<!-- HTML -->
<figure class="aden">
  <img src="../img.png">
</figure>

Alternatively, you can just download and link to any individual css file (e.g. <link rel="stylesheet" href="css/vendor/aden.min.css">) if you're using only one of the styles.

Available Classes

For use in HTML markup:

1977: class="_1977"
Aden: class="aden"
Amaro: class="amaro"
Brannan: class="brannan"
Brooklyn: class="brooklyn"
Clarendon: class="clarendon"
Gingham: class="gingham"
Hudson: class="hudson"
Inkwell: class="inkwell"
Kelvin: class="kelvin"
Lark: class="lark"
Lo-fi: class="lofi"
Mayfair: class="mayfair"
Moon: class="moon"
Nashville: class="nashville"
Perpetua: class="perpetua"
Reyes: class="reyes"
Rise: class="rise"
Slumber: class="slumber"
Stinson: class="stinson"
Toaster: class="toaster"
Valencia: class="valencia"
Walden: class="walden"
Willow: class="willow"
X-Pro-2: class="xpro2"

Use Sass `@extend` or `@mixin`

If you use custom naming in your CSS architecture, you can add the .scss files for the provided styles within your project and then @extend the filter effects within your style definitions. If you think extends are stupid, I will fight you 😊 .

Download the scss/ folder contents

Include a link to scss/cssgram.scss via an @import statement in your Sass manifest file (i.e. main.scss). It may look like: @import 'vendor/cssgram'
Extend the placeholder selector (e.g. @extend %aden or using mixins @include aden()) in your element.

For example:

<!-- HTML -->
<figure class="viz--beautiful">
  <img src="../img.png">
</figure>

// Sass
.viz--beautiful {
  @extend %aden;
}

or using mixins (more flexible)

// Sass (without adding new CSS3 filters)
.viz--beautiful {
  @include aden();
}

// Sass (adding new CSS3 filters)
.viz--beautiful {
  @include aden(blur(2px) /*...*/);
}

Alternatively, if you're using only one of the styles, you can download and link any individual .scss file in your Sass manifest (i.e. scss/aden.scss).

Available Placeholders

For use in Sass stylesheets:

Extends

1977: @extend %_1977
Aden: @extend %aden
Amaro: @extend %amaro
Brannan: @extend %brannan
Brooklyn: @extend %brooklyn
Clarendon: @extend %clarendon
Gingham: @extend %gingham
Hudson: @extend %hudson
Inkwell: @extend %inkwell
Kelvin: @extend %kelvin
Lark: @extend %lark
Lo-fi: @extend %lofi
Mayfair: @extend %mayfair
Moon: @extend %moon
Nashville: @extend %nashville
Perpetua: @extend %perpetua
Reyes: @extend %reyes
Rise: @extend %rise
Slumber: @extend %slumber
Stinson: @extend %stinson
Toaster: @extend %toaster
Valencia: @extend %valencia
Walden: @extend %walden
Willow: @extend %willow
X-Pro-2: @extend %xpro2

Mixins (You can add more CSS3 filters as arguments)

1977: @include _1977()
Aden: @include aden()
Amaro: @include amaro()
Brannan: @include brannan()
Brooklyn: @include brooklyn()
Clarendon: @include clarendon()
Gingham: @include gingham()
Hudson: @include hudson()
Inkwell: @include inkwell()
Kelvin: @include kelvin()
Lark: @include lark()
Lo-fi: @include lofi()
Mayfair: @include mayfair()
Moon: @include moon()
Nashville: @include nashville()
Perpetua: @include perpetua()
Reyes: @include reyes()
Rise: @include rise()
Slumber: @include slumber()
Stinson: @include stinson()
Toaster: @include toaster()
Valencia: @include valencia()
Walden: @include walden()
Willow: @include willow()
X-Pro-2: @include xpro2()

Contributing

Either:

Create an issue

Or:

Fork this repository
Clone the fork onto your system
npm install dependencies (must have Node installed)
Run gulp to compile CSS and the test site
Make changes and check the test site with your changes (see file structure outline below)
Submit a PR referencing the issue with a smile 😄

Filters are really fun to create! Reference photos created by Miles Croxford can be found here.

File Structure Outline

source/css/cssgram.css contains each of the CSS classes you can apply to your <img> to give it the filter. You should use source/css/cssgram.min.css for production if you want access to all of the library
source/scss/ contains the source files for individual classes and placeholder selectors you can use to extend CSS classes in Sass
site/ is the public facing website
site/test is how you test filters if you're developing, remember to change is_done for the filter you are creating in site/filters.json.

Note: This will also have mixin options and a PostCSS Component.

Comments

Add test sheet

NB. I made it so the instagram pictures are in /ref just incase instagram remove the pictures from the cssgram account or the person developing the filter has no internet access

opened by m1 10
Fixed duplicate code

replaced the extend approach with mixins to avoid generating.

I'm really sorry for the messed up commits. I had some problems with my Git tool before the pull request was created 🙇 😞

opened by DeMuu 8
CSSgram doesn't play well with CSS transformations

If you put a filter on something like this https://desandro.github.io/3dtransforms/docs/card-flip.html the whole thing will pretty much just break (using chrome). Not sure if it's even possible to fix that on CSS level though.

PS.: I will do a jsfiddle later once I find a few free minutes.

opened by mxmzb 8
re-added slumber
I modified the filter a bit. What do you think?

Also, about the test twig file, I figured the line 38 of site/test/index.twig

<figure class="{{f.name}}">

Shouldn't it be

<figure class="{{f.usage}}">

instead so the figures get the class name in lowercase instead of capitalized? (e.g 'slumber' instead of 'Slumber')
opened by shelune 5

Single Source of Truth for Site & Test Page

Currently both use their own filters list:

test page:

  {% set filters = [
    {name: 'aden',       is_done: true},
    {name: 'amaro',      is_done: false},
    {name: 'brannan',    is_done: false},
    {name: 'crema',      is_done: false},
    {name: 'earlybird',  is_done: true},
    {name: 'hefe',       is_done: false},
    {name: 'hudson',     is_done: true},
    {name: 'inkwell',    is_done: true},
    {name: 'juno',       is_done: false},
    {name: 'lark',       is_done: true},
    {name: 'lofi',       is_done: true},
    {name: 'ludwig',     is_done: false},
    {name: 'mayfair',    is_done: true},
    {name: 'nashville',  is_done: true},
    {name: 'perpetua',   is_done: true},
    {name: 'reyes',      is_done: true},
    {name: 'rise',       is_done: false},
    {name: 'sierra',     is_done: false},
    {name: 'slumber',    is_done: false},
    {name: 'valencia',   is_done: false},
    {name: 'willow',     is_done: false},
    {name: 'xpro2',      is_done: true},
  ] %}

demo site:

  {% set filters = [
    {name: 'Aden',       usage: 'aden'},
    {name: 'Reyes',      usage: 'reyes'},
    {name: 'Perpetua',   usage: 'perpetua'},
    {name: 'Inkwell',    usage: 'inkwell'},
    {name: 'Earlybird',  usage: 'earlybird'},
    {name: 'Toaster',    usage: 'toaster'},
    {name: 'Walden',     usage: 'walden'},
    {name: 'Hudson',     usage: 'hudson'},
    {name: 'Gingham',    usage: 'gingham'},
    {name: 'Mayfair',    usage: 'mayfair'},
    {name: 'Lo-Fi',      usage: 'lofi'},
    {name: 'X-Pro2 II',  usage: 'xpro2'},
    {name: '1977',       usage: '_1977'},
    {name: 'Brooklyn',   usage: 'brooklyn'},
    {name: 'Nashville',  usage: 'nashville'},
    {name: 'Lark',       usage: 'lark'},
  ] %}

These could likely be combined:

  {% set filters = [
     {name: 'Aden',      is_done: true,      usage: 'aden'},
     {name: 'Amaro',     is_done: false,     usage:'tbd'},
  ] %}

And only the finished filters would show up with usage on the demo site. That being said, we need parity with all of the test files and existing filters that exist first See #96

demo site test site refactor

opened by una 5

Dev build

Implementation for #239 😄

In summary,

gulp: starts dev server, watch & do compilations to .dev folder

in master: gulp build: does compilation, files are generated in the respective folders gulp server: starts server in root to view compiled files after master build

(I removed compiled files of Amaro filter which is currently unavailable. Also did reset for Kelvin filter is_done status, it had got reset in one of the previous commits. Sorry to keep it in the same PR.)

opened by Praseetha-KR 4
optimize png images using zopflipng
Use Google's zopflipng to re-compress the png images losslessly as below:

site/img/cssgram-logo.png | Bin 40651 -> 32022 bytes site/img/logo-temp.png | Bin 15951 -> 9328 bytes
opened by PeterDaveHello 4
Added Contributing file with information

I happened to miss the contribution section in the Readme while looking through the project. As many others do, I was looking for the CONTRIBUTING.md file in the repository, but couldn't find it. I suggest we add it with this pull request 👍

opened by Bobeta 4
Make this library (SASS source) extensible.
Q: What this PR fixes? A: Allows add filter to an existing CSSgram filter (only using SASS)

Q: Why? A: CSS3 filter property does not allow inheritance, you cannot 'add' new filters keeping the existing filters

Before:

figure { @extend %aden; &:hover{ filter: blur(2px); // overrides Aden filter, now has only blur filter } }

Now:

figure { @extend %aden; // or @include aden; &:hover{ @include aden(blur(2px) /*...*/); // Aden filter still works, but now blur filter was 'added' } }

PS: Now comments are compatible with SassDoc.

:smile:
opened by bunomonteiro 4
Check out postcss-instagram

You might wanna check out the postcss-instagram plugin for PostCSS for inspiration.

I really like where you're going with this though and great name choice! :smile: :+1:

opened by himynameisdave 4
Is this legal?

Thanks for this great library!

I was wondering, is it actually legal to use these filter effect on websites and commercial platforms?

Does Instagram allow this?

Surely the names themselves must have a trademark on them?

And what about the algorithms? I guess these approximate the original Instagram effects, not being pixel perfect copies?

opened by ziriax 0

Releases(0.1.12)

0.1.12(Nov 11, 2016)

Thank you to @LadyCarni and #251, we now have STINSON!

Source code(tar.gz)
Source code(zip)
0.1.11(Nov 3, 2016)
New filter (Maven) thanks to @LadyCarni and #252

Additional updates:

template update in /test/

updated Gingham filter

Source code(tar.gz)
Source code(zip)
0.1.10(Oct 6, 2016)

Another fantastic filter by @Praseetha-KR! #210

Source code(tar.gz)
Source code(zip)
0.1.9(Oct 3, 2016)

Thanks to the awesome work of @Praseetha-KR we have the Valencia filter!!

Source code(tar.gz)
Source code(zip)
0.1.8(Sep 28, 2016)

Brannan filter now available to all!

(could probably use some touchups though :) )

Source code(tar.gz)
Source code(zip)
0.1.7(Mar 11, 2016)
You can now use Sass mixins to @include filters!!

Shoutout to @bunomonteiro on #156

Mixins allow for multiple filter arguments to be passed into your classes. This is useful for if you want to add filters in addition to the ones provided (i.e. add a blur).

To use:

Download the /scss folder contents

Include a link to scss/cssgram.scss via an import statement in your Sass manifest file (i.e. main.scss). It may look like: @import 'vendor/cssgram';

Include the mixin @include aden() in your element.

For example:

<figure class="viz--beautiful"> <img src="../img.png"> </figure>

// Sass .viz--beautiful { @include aden() }

As mentioned above, you can also add additional filters as arguments when using the library with mixins:

// Sass .viz--beautiful { @include @include aden(blur(2px) /*...*/); }

Available Mixins:

1977: @include _1977();

Aden: @include aden();

Brooklyn: @include brooklyn();

Clarendon: @include clarendon();

Earlybird: @include earlybird();

Gingham: @include gingham();

Hudson: @include hudson();

Inkwell: @include inkwell();

Lark: @include lark();

Lo-Fi: @include lofi();

Mayfair: @include mayfair();

Moon: @include moon();

Nashville: @include nashville();

Perpetua: @include perpetua();

Reyes: @include reyes();

Rise: @include rise();

Slumber: @include slumber();

Toaster: @include toaster();

Walden: @include walden();

Willow: @include willow();

X-pro II: @include xpro2();

Source code(tar.gz)
Source code(zip)
0.1.6(Jan 28, 2016)

Slumber is added!

Source code(tar.gz)
Source code(zip)
0.1.5(Jan 27, 2016)

:sparkles: New Filter Alert -- Rise :sparkles:
Source code(tar.gz)
Source code(zip)
0.1.4(Dec 19, 2015)

Two new filters for the family!
Source code(tar.gz)
Source code(zip)
0.1.3(Nov 30, 2015)

New Filters Added!
Source code(tar.gz)
Source code(zip)
0.1.2(Nov 13, 2015)
added :before pseudo element to base style

added Nashville filter

Source code(tar.gz)
Source code(zip)
0.1.1(Nov 9, 2015)
We now have a test page for trying out features! Thanks for your work @m1! See #87 for more information.

Additional changes:

Using a templating engine to serve the site and test page

Moved site css into an individual directory to not clutter source/ #89

This should make contribution much easier :raised_hands:
Source code(tar.gz)
Source code(zip)
0.1.0(Nov 5, 2015)
Available Classes

For use in HTML markup:

Aden: class="aden"

Reyes: class="reyes"

Perpetua: class="perpetua"

Inkwell: class="inkwell"

Toaster: class="toaster"

Walden: class="walden"

Hudson: class="hudson"

Gingham: class="gingham"

Mayfair: class="mayfair"

Lo-fi: class="lofi"

X-Pro II: class="xpro2"

1977: class="_1977"

Brooklyn: class="brooklyn"

Available Extends

For use in Sass elements:

Aden: @extend %aden;

Reyes: @extend %reyes;

Perpetua: @extend %perpetua;

Inkwell: @extend %inkwell;

Toaster: @extend %toaster;

Walden: @extend %walden;

Hudson: @extend %hudson;

Gingham: @extend %gingham;

Mayfair: @extend %mayfair;

Lo-fi: @extend %lofi;

X-Pro II: @extend %xpro2;

1977: @extend %_1977;

Brooklyn: @extend %brooklyn;

Source code(tar.gz)
Source code(zip)