Have ideas to improve npm?Join in the discussion! »

    sass-web-fonts

    2.1.0 • Public • Published

    Sass Web Fonts

    A Sass mixin to allow easy, efficient usage of Google Web Fonts.

    You can clone this repo and include _web-fonts.scss in your project manually, or you can install the sass-web-fonts package from npm or Bower.

    Upgrading from a previous version of Sass Web Fonts

    Sass Web Fonts 2.x introduces breaking changes from 1.x. If you're upgrading from Sass Web Fonts 1.x, read the upgrading guide. It's very easy. :)

    Usage

    First, import Sass Web Fonts like this:

    @import "web-fonts";

    Installing with npm and using a node-based task-runner

    1. Add Sass-Web-Fonts as a dependency:

      npm install --save sass-web-fonts
    2. You’ll need to add Sass-Web-Fonts to your node-sass includePaths option. Commonly in this way: require("sass-web-fonts").includePaths. But specifically you have to refer to the framework you are using.

    With Grunt

    const sass = require( "node-sass" );
     
    module.exports = function( grunt ) {
        require( "load-grunt-tasks" )( grunt );
     
        grunt.initConfig( {
            sass: {
                options: {
                    implementation: sass,
                    sourceMap: false,
                    outputStyle: "compressed",
                    sourceComments: false,
     
                    includePaths: [
                        //require( "module-one" ).includePaths,
                        //require( "module-two" ).includePaths,
                        require( "sass-web-fonts" ).includePaths
                    ]
                },
                public: {
                    files: {
                        "master.css": "master.scss"
                    }
                }
            }
      } );
    };

    With Gulp

    var gulp = require( "gulp" );
    var sass = require( "gulp-sass" );
     
    gulp.task( "sass", function () {
      gulp.src( "input.scss" )
        .pipe( sass( {
          includePaths: require( "sass-web-fonts" ).includePaths
        } ) )
        .pipe( gulp.dest( "output.css" ) );
    } );

    Using with libsass

    If you are using libsass, you can't pass the result of web-fonts-url() directly into @import url(). You have to store it in a variable first. This is due to the compiler not supporting importing urls from functions.

    // This won't work with libsass 
    @import url(web-fonts-url("Open Sans"));
     
    // This will work with libsass 
    $url: web-fonts-url("Open Sans");
    @import url($url);

    Importing a single font

    @import url(web-fonts-url("Open Sans"));

    Specifying font variant

    @import url(web-fonts-url(("Open Sans": "bold")));

    Multiple variants

    @import url(web-fonts-url(("Open Sans": ("500", "600 italic"))));

    Multiple fonts

    @import url(web-fonts-url("Open Sans", ("Ubuntu": ("400", "italic"))));

    Protocols

    By default, the web-fonts mixin will attempt to load fonts with the same protocol that was used to access the stylesheet it was called in. However, in some circumstances, most notably when the stylesheet was loaded as a local file (using a file:// url), this will not work. In this situation, it is possible to override the automatic protocol detection by setting the $web-fonts-protocol variable prior to calling the mixin.

    Example

    $web-fonts-protocol: "https"; // fonts will be loaded over HTTPS from here on. 
    @import url(web-fonts-url("Open Sans"); // uses HTTPS); 

    Extra parameters

    To add additional parameters to the web fonts URL, you can override the $web-fonts-params variable with a map containing the extra URL params. For example, you can use it to specify character subsets:

    $web-fonts-params: (subset: "latin,latin-ext");
    @import url(web-fonts-url("Open Sans"));
    /* Generated CSS */
    @import url("//fonts.googleapis.com/css?subset=latin%2Clatin-ext&family=Open%20Sans");

    A list of available parameters can be found in the Google Web Fonts documentation.

    Testing

    Development of this mixin uses SassUnit for unit tests. To run the tests after making a change to the mixin, do this:

    $ bundle install
    $ bundle exec sassunit

    Codeship Status for alyssais/Sass-Web-Fonts

    Troubleshooting

    If you get a Sass::SyntaxError when using the library, you probably need to update Sass. See issue #7 for more information.


    Requires Sass 3.3 or later version. Pull requests welcome.

    Install

    npm i sass-web-fonts

    DownloadsWeekly Downloads

    289

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    16.5 kB

    Total Files

    39

    Last publish

    Collaborators

    • avatar