Lists

Introduction

JigSass Lists is a collection of unopinionated, unstyled, ui abstractions for displaying lists.

GitHub page

Installation

Using npm:

npm i -S jigsass-objects-lists

Usage

First, you need to import JigSass Lists into your stylesheet:

@import 'path/to/jigsass-objects-lists/scss/index';

And optionally reconfigure the defaults to your liking.

JigSass Lists provides the following list abstractions:

  • Bare list: Unstyled lists.
  • Inline list: Inlined list items, placed side by side instead of stacked one on top of another
  • Delimited inline list: An inline list, in which items are delimited by a configurable string.
  • Split inline list: Push the first or last list item away from the other items, to the edge of the container
  • Divided list: A vertically stacked list of items divided by horizontal rules.

Like all other JigSass modules, JigSass List does not automatically generate any CSS when imported. In order to use its classes, you would have to first explicitly indicate your intention to use them by enabling their generation in the associated configurations map, Leaving us only with CSS we need.

All JigSass List classes are responsive using JigSass MQ and the breakpoints defined in [$jigsass-breakpoints](https://txhawks.github.io/jigsass-tools-mq/#variable-jigsass-breakpoints).

Based enabled selectors in the configuration map, responsive modifiers are generated according to the following logic:

.o-<list-abstraction>--modifier[-[-from-{breakpoint-name}][-until-{breakpoint-name}][-misc-{breakpoint-name}]]

So, assuming the medium, large and landscape breakpoints are defined in $jigsass-breakpoints as 600px, 1024px and (orientation: landscape) respectively,

$jigsass-list-inline-conf: (
  no-breakpoint: (
    split-first: true,
  ),
  until-medium: (
    split-first: true,
  ),
  from-large-when-landscape: (
    split-first: true,
  ),
)

will generate the following classes:

  • .o-inline-list--split-first, which is not limited to any media-query.
  • .o-inline-list--split-first--until-medium, which will be in effect at (max-width: 37.49em) and will override styles in the default class until that point.
  • .o-inline-list--split-first--from-large-when-landscape, which will go into effect at (min-width: 64em) and (orientation: landscape) and will override styles in the default class under these conditions.

License: MIT

CSS Outpout

By default, JigSass Lists does not generate any CSS output when imported into a stylesheet. CSS output must be enabled on a per-selector basis, inside the dedicated configuration maps:

Bare list and modifier classes

$jigsass-list-bare-conf

Type: Map

Configuration map for enabling generation of bare-list and bare-list modifier classes.

Default:

$jigsass-list-bare-conf: (
  no-breakpoint: (
    no-modifier: false,
  ),
);

Example:

$jigsass-list-bare-conf: (
  no-breakpoint: (
    no-modifier: true,  // Enables generation of the `.o-bare-list`
                        // class outside of any media query.
  ),
  from-<bp-name>: (
    no-modifier: true,  // Enables generation of the `.o-bare-list--from-<bp-name>`
                        // class inside a min-width media query
                        // defined ins `$jigsass-breakpoints.length`.
  ),
  until-<bp-name>: (
    no-modifier: true,  // Enables generation of the `.o-bare-list--until-<bp-name>`
                        // class inside a max-width media query
                        // defined ins `$jigsass-breakpoints.length`.
  ),
  when-<bp-name>: (
    no-modifier: true,  // Enables generation of the `.o-bare-list--when-<bp-name>`
                        // class inside a misc media query
                        // defined ins `$jigsass-breakpoints.features`.
  ),
  from-<bp-name>-until-<bp-name>: (...);
  from-<bp-name>-when-<bp-name>: (...);
  until-<bp-name>-when-<bp-name>: (...);
  from-<bp-name>-until-<bp-name>-when-<bp-name>: (...);
);

Inline list and modifier classes

$jigsass-list-inline-conf

Type: Map

Configuration map for enabling generation of inline-list and inline-list modifier classes.

Default:

$jigsass-list-inline-conf: (
  no-breakpoint: (
    no-modifier: false,
    delimited: false,
    split-first: false,
    split-last: false,
    spread: false,
  ),
);

Example:

$jigsass-list-inline-conf: (
  no-breakpoint: (
    // Enables generation of the `.o-inline-list`
    // class outside of any media query.
    no-modifier: true,
    // Enables generation of the `.o-inline-list--spread`
    // modifier class outside of any media query.
    spread: true,
  ),
  from-<bp-name>: (
    // Enables generation of the `.o-inline-list--from-<bp-name>`
    // class inside a min-width media query
    // defined ins `$jigsass-breakpoints.length`.
    no-modifier: true,
    // Enables generation of the `.o-inline-list--spread--from-<bp-name>`
    // class inside a min-width media query
    // defined ins `$jigsass-breakpoints.length`.
    spread: true,
  ),
  until-<bp-name>: (
    // Enables generation of the `.o-inline-list--until-<bp-name>`
    // class inside a max-width media query
    // defined ins `$jigsass-breakpoints.length`.
    no-modifier: true,
    // Enables generation of the `.o-inline-list--spread--until-<bp-name>`
    // class inside a max-width media query
    // defined ins `$jigsass-breakpoints.length`.
    spread: true,
  ),
  when-<bp-name>: (
    // Enables generation of the `.o-inline-list--when-<bp-name>`
    // class inside a misc media query
    // defined ins `$jigsass-breakpoints.features`.
    no-modifier: true,
    // Enables generation of the `.o-inline-list--spread--when-<bp-name>`
    // class inside a misc media query
    // defined ins `$jigsass-breakpoints.features`.
    spread: true,
  ),
  from-<bp-name>-until-<bp-name>: (...);
  from-<bp-name>-when-<bp-name>: (...);
  until-<bp-name>-when-<bp-name>: (...);
  from-<bp-name>-until-<bp-name>-when-<bp-name>: (...);
);

Divided list and modifier classes

$jigsass-list-divided-conf

Type: Map

Configuration map for enabling generation of divided-list and divided-list modifier classes.

Default:

$jigsass-list-divided-conf: (
  no-breakpoint: (
    no-modifier: false,

    // Enable border modifiers here,
    // based on the ones defined in
    // `$jigsass-lists-divided-border-modifiers`
  ),
);

Example:

$jigsass-list-divided-conf: (
  no-breakpoint: (
    // Enables generation of the `.o-divided-list`
    // class outside of any media query.
    no-modifier: true,

    // Enables generation of the `.o-divided-list--foo`
    // modifier class outside of any media query.
    foo: true,
  ),
  from-<bp-name>: (
    // Enables generation of the `.o-divided-list--from-<bp-name>`
    // class inside a min-width media query
    // defined ins `$jigsass-breakpoints.length`.
    no-modifier: true,

    // Enables generation of the `.o-divided-list--foo--from-<bp-name>`
    // class inside a min-width media query
    // defined ins `$jigsass-breakpoints.length`.
    foo: true,
  ),
  until-<bp-name>: (
    // Enables generation of the `.o-divided-list--until-<bp-name>`
    // class inside a max-width media query
    // defined ins `$jigsass-breakpoints.length`.
    no-modifier: true,

    // Enables generation of the `.o-divided-list--foo--until-<bp-name>`
    // class inside a max-width media query
    // defined ins `$jigsass-breakpoints.length`.
    foo: true,
  ),
  when-<bp-name>: (
    // Enables generation of the `.o-divided-list--when-<bp-name>`
    // class inside a misc media query
    // defined ins `$jigsass-breakpoints.features`.
    no-modifier: true,

    // Enables generation of the `.o-divided-list--foo--when-<bp-name>`
    // class inside a misc media query
    // defined ins `$jigsass-breakpoints.features`.
    foo: true,
  ),
  from-<bp-name>-until-<bp-name>: (...);
  from-<bp-name>-when-<bp-name>: (...);
  until-<bp-name>-when-<bp-name>: (...);
  from-<bp-name>-until-<bp-name>-when-<bp-name>: (...);
);

Configuration

JigSass Lists allows for some modification through tweaking configuration variable. To override the default values, predefine them to your own needs before importing JigSass Lists.

Flexbox support

$jigsass-lists-flexbox

Type: Boolean

Determines if flexbox should be enables, where relevant

Default: true

Flexbox Fallback

$jigsass-lists-flexbox-fallback

Type: Boolean or String

Determines if flexbox fallback should be included and the qualifier class to use if so (e.g, .no-flexbox when using Modernizr defaults)

Set to false to disable fallback altogether, and to a class-name (sans the leading .) used as the qualifier class if fallback is desirable.

Default: 'no-flexbox'

Inline Delimiter

$jigsass-lists-inline-delimiter

Type: String

The default delimiter to use with .o-inline-list--delimited.

Default: '\2002|\2002'

Divided lists border defaults

$jigsass-lists-divided-border

Type: List

Sets the default border and padding above devided-lists' list items.

A list of arguments for the [jigsass-border-top](http://tinyurl.com/js-border-top) mixin in the following order:

  • A number in pixels. The border's width.
  • A unitless number. The number of typographic lines occupied by the border and padding added together.
  • A string. The border's style (e.g., solid, dotted, etc.).

Default: 1px 2 solid

Divided lists border modifiers

$jigsass-lists-divided-border-modifiers

Type: Map

Border modifiers for divided lists.

A map where each key is a modifier's name and its value is a list in the same format used in [$jigsass-lists-divided-border](#jigsass-lists-divided-border).

Default: (tight: 1px 2 solid, loose: 1px 4 solid, x-loose: 1px 8 solid)

Bare List

Strip lists of their default decoration (bullets, numbers, etc.) and spacing.

Usage example:

  <ul class='bare-list'>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>

CSS output: 

  // --- CSS --- //
  .o-bare-list {
    list-style: none;
  }

Inline List

Place list (or fuax-list) elements side by side instead of stacked one on top of each other.

Usage example:

  <ul class='inline-list'>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>

CSS output: 

  // --- CSS --- //
  .o-inline-list > * {
    display: inline-block;
  }

Delimited Inline List

Delimit an inline-list by the string defined in $jigsass-lists-inline-delimiter

Override the delimiter of individual list items by setting the data-jigsass-delimiter property in the HTML to the overriding delimitier:

- `$jigsass-lists-inline-delimiter` (default: `'\2002|\2002'`):
  The default delimiter to use with `.o-inline-list--delimited`.

Usage example

  <ul class='[ o-inline-list o-inline-list--delimited ]'>
    <li data-jigsass-delimiter=':&nbsp;'><strong>Default delimiters</strong></li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>

  <ul class='[ o-inline-list o-inline-list--delimited ]'>
    <li data-jigsass-delimiter=':&nbsp;'><strong>Custom delimiters</strong></li>
    <li data-jigsass-delimiter=',&nbsp'>item 2</li>
    <li data-jigsass-delimiter=',&nbsp'>item 3</li>
    <li data-jigsass-delimiter=',&nbsp'>item 4</li>
    <li data-jigsass-delimiter=',&nbsp'>item 5</li>
  </ul>

CSS output: 

  // --- CSS --- //
  .o-inline-list--delimited {
    letter-spacing: -0.31em;
    text-rendering: optimizespeed;
  }

  opera:-o-prefocus .o-inline-list--delimited,
  .o-inline-list--delimited {
    word-spacing: -.043em;
  }

    .o-inline-list--delimited > * {
      display: inline-block;
      letter-spacing: normal;
      text-rendering: auto;
      word-spacing: normal;
    }

    .o-inline-list--delimited > *:not(:last-child):after {
      content: $jigsass-lists-inline-delimiter;
    }

    .o-inline-list--delimited > *[data-jigsass-delimiter]:not(:last-child):after {
      content: attr(data-jigsass-delimiter);
    }

Split Inline List (first)

Push all items in an inline list past the first one to the horizontal end of the container.

- '$jigsass-lists-flexbox' (default: true):
  Determines if flexbox should be enables, where relevant
- '$jigsass-lists-flexbox-fallback' (default: 'no-flexbox'):
  Determines if flexbox fallback should be included and the qualifier class
  to use if so (e.g, `.no-flexbox` when using Modernizr defaults)
  Set to `false` to disable fallback altogether, and to a class-name
  (sans the leading `.`) used as the qualifier class if fallback is
  desirable.

Usage example:

  <ul class='u-maw--600px [ fpo fpo--b ]  [ o-inline-list o-inline-list--split-first ]'>
  <li><strong>Pushed to the edge</strong></li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>

CSS output: 

  // --- CSS --- //

  // When flexbox is enabled
  .o-inline-list--split-first {
    display: flex;
  }

    .o-inline-list--split-first > * {
      flex-grow: 0;
    }

    .o-inline-list--split-first > *:first-child {
      margin-(left|right): auto;
    }

  // When support for flexbox fallback is needed
  .no-flexbox .o-inline-list--split-first {
    display: table;
  }

    .no-flexbox .o-inline-list--split-first > * {
      display: table-cell;
      white-space: nowrap;
    }

    .no-flexbox .o-inline-list--split-first > *:first-child {
      max-width: 100%;
      width: 10000px;
    }

  // When flexbox is disabled
  .o-inline-list--split-first {
    display: table;
  }

    .o-inline-list--split-first > * {
      display: table-cell;
      white-space: nowrap;
    }

    .o-inline-list--split-first > *:first-child {
      max-width: 100%;
      width: 10000px;
    }

Split Inline List (last)

Push the last item in an inline list to the horizontal end of the container.

- '$jigsass-lists-flexbox' (default: true):
  Determines if flexbox should be enables, where relevant
- '$jigsass-lists-flexbox-fallback' (default: 'no-flexbox'):
  Determines if flexbox fallback should be included and the qualifier class
  to use if so (e.g, `.no-flexbox` when using Modernizr defaults)
  Set to `false` to disable fallback altogether, and to a class-name
  (sans the leading `.`) used as the qualifier class if fallback is
  desirable.

Usage example:

  <ul class='u-maw--600px [ fpo fpo--b ]  [ o-inline-list o-inline-list--split-last ]'>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li><strong>Pushed to the edge</strong></li>
  </ul>

CSS output: 

  // --- CSS --- //

  // When flexbox is enabled
  .o-inline-list--split-last {
    display: flex;
  }

    .o-inline-list--split-last > * {
      flex-grow: 0;
    }

    .o-inline-list--split-last > *:last-child {
      margin-(left|right): auto;
    }

  // When support for flexbox fallback is needed
  .no-flexbox .o-inline-list--split-last {
    display: table;
  }

    .no-flexbox .o-inline-list--split-last > * {
      display: table-cell;
      white-space: nowrap;
    }

    .no-flexbox .o-inline-list--split-last > *:last-child {
      max-width: 100%;
      text-align: (left|right);
      width: 10000px;
    }

  // When flexbox is disabled
  .o-inline-list--split-last {
    display: table;
  }

    .o-inline-list--split-last > * {
      display: table-cell;
      white-space: nowrap;
    }

    .o-inline-list--split-last > *:last-child {
      max-width: 100%;
      text-align: (left|right);
      width: 10000px;
    }

Spread out Inline List

// Equally spread list items to fill the full (fluid) // width of their container Push all items in an inline list past the first one to the horizontal end of the container.

- '$jigsass-lists-flexbox' (default: true):
  Determines if flexbox should be enables, where relevant
- '$jigsass-lists-flexbox-fallback' (default: 'no-flexbox'):
  Determines if flexbox fallback should be included and the qualifier class
  to use if so (e.g, `.no-flexbox` when using Modernizr defaults)
  Set to `false` to disable fallback altogether, and to a class-name
  (sans the leading `.`) used as the qualifier class if fallback is
  desirable.

Usage example:

  <ul class='[ o-inline-list o-inline-list--spread ]'>
    <li class='fpo'>item 1</li>
    <li class='fpo'>item 2</li>
    <li class='fpo'>
      <strong>I'm much longer than the others, two lines I will take</strong>
    </li>
    <li class='fpo'>item 3</li>
    <li class='fpo'>item 4</li>
  </ul>

CSS output: 

  // --- CSS --- //

  // When flexbox is enabled
  .o-inline-list--spread {
    display: flex;
    flex-basis: 100%;
    flex-wrap: nowrap;
  }

    .o-inline-list--spread > * {
      flex-grow: 1;
      flex-shrink: 1;
    }

  // When support for flexbox fallback is needed
  .no-flexbox .o-inline-list--spread {
    display: table;
    table-layout: fixed;
  }

    .no-flexbox .o-inline-list--spread > * {
      display: table-cell;
    }

  // When flexbox is disabled
  .o-inline-list--spread {
    display: table;
    table-layout: fixed;
  }

    .o-inline-list--spread > * {
      display: table-cell;
    }

Divided List

A vertically stacked list of items divided by lines.

This object sets only very minimal styling and relies on being complemented with component and utility classes, e.g., .u-as for spacing items from one another.

Related variables:

- `$jigsass-lists-divided-border-modifiers` (default: `1px 2 solid`):
A list of arguments for the `[jigsass-border-top](http://tinyurl.com/js-border-top)` mixin in the following order:
  - A number in pixels. The border's width.
  - A unitless number. The number of
  [typographic lines](https://txhawks.github.io/jigsass-tools-typography/) occupied
  by the border and padding added together.
  - A string. The border's style (e.g., `solid`, `dotted`, etc.).



  Border modifiers for divided lists.
  A map where each key is a modifier's name and its value is a
  list in the same format used in [$jigsass-lists-divided-border](divided-lists-border-defaults).

Usage example:

  <ul class='u-as--2 o-divided-list'>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>

CSS output: 

  // --- CSS --- //
  .o-divided-list {
    display: block;
  }
    .o-divided-list > * + * {
      border-top: 1px;
      padding-top: 11px;
    }

Divided List (tight)

Modifies the default border and padding above list items in a devided-list.

Related variables:

- `$jigsass-lists-divided-border-modifiers` (default: `1px 2 solid`):
  Border modifiers for divided lists.
  A map where each key is a modifier's name and its value is a
  list in the same format used in [$jigsass-lists-divided-border](divided-lists-border-defaults).

Usage example:

  <ul class='u-as--1  [ o-divided-list o-divided-list--tight ]'>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>

Divided List (loose)

Modifies the default border and padding above list items in a devided-list.

Related variables:

- `$jigsass-lists-divided-border-modifiers` (default: `1px 2 solid`):
  Border modifiers for divided lists.
  A map where each key is a modifier's name and its value is a
  list in the same format used in [$jigsass-lists-divided-border](divided-lists-border-defaults).

Usage example:

  <ul class='u-as--4  [ o-divided-list o-divided-list--loose ]'>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>

Divided List (x-loose)

Modifies the default border and padding above list items in a devided-list.

Related variables:

- `$jigsass-lists-divided-border-modifiers` (default: `1px 2 solid`):
  Border modifiers for divided lists.
  A map where each key is a modifier's name and its value is a
  list in the same format used in [$jigsass-lists-divided-border](divided-lists-border-defaults).

Usage example:

  <ul class='u-as--8  [ o-divided-list o-divided-list--x-loose ]'>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
    <li>item 4</li>
    <li>item 5</li>
  </ul>