@financial-times/o-teaser-collection

# o-teaser-collection This component is for displaying collections of [o-teasers](http://registry.origami.ft.com/components/o-teaser). - [Usage](#usage) - [Markup](#markup) - [Sass](#sass) - [Migration guide](#migration-guide) - [Contact](#contact) - [Licence](#licence) ## Usage Check out [how to include Origami components in your project](https://origami.ft.com/documentation/components/#including-origami-components-in-your-project) to get started with `o-teaser-collection`. ## Markup The basic markup structure for a teaser collection will look something like this: ```html <div class="o-teaser-collection"> <h2 class="o-teaser-collection__heading"> <a class="o-teaser-collection__heading-link" href="#">UK</a> </h2>  </div> ``` Teaser collections can be arranged using [o-grid](http://registry.origami.ft.com/components/o-grid), or by using the `o-teaser-collection__items` and `o-teaser-collection__item` classes. These classes are designed to work on list elements, as seen in the `o-teaser-collection--numbered` example: ```html <div class="o-teaser-collection o-teaser-collection--numbered"> <h2 class="o-teaser-collection__heading o-teaser-collection__heading--full-width" > Most read </h2> <ol class="o-teaser-collection__items"> <li class="o-teaser-collection__item">teaser goes here</li> <li class="o-teaser-collection__item">teaser goes here</li> </ol> </div> ``` Teaser Collections can be customised using several [modifier classes](#options). ## Sass To include all styles call the `oTeaserCollection` mixin. ```scss @include oTeaserCollection(); ``` ### Options `o-teaser-collection` css may be included granularly by passing options to the `oTeaserCollection` mixin. ```scss @include oTeaserCollection( $opts: ( 'collections': ( 'special', ), // o-teaser-collection--special 'headings': ( 'inverse', ), // o-teaser-collection__heading--inverse 'items': ( 'stretched', ) // o-teaser-collection__item--stretched,,,,,,,, ) ); ``` Options include: | Key | Possible Values | Classes Output | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | collections | 'horizontal', 'special', 'numbered', 'big-story', 'assassination', 'assassination-related', 'mid-slice', 'stream', 'top-standalone' | `o-teaser-collection--[option]`. Apply to `o-teaser-collection`, e.g. `class="o-teaser-collection o-teaser-collection--horizontal"` | | headings | 'inverse', 'full-width', 'half-width', 'small' | `o-teaser-collection__heading--[option]`. Apply to `o-teaser-collection__heading`, e.g. `class="o-teaser-collection__heading o-teaser-collection__heading--inverse"` | | items | 'stretched' | `o-teaser-collection__item--[option]`. Apply to `o-teaser-collection__item`, e.g. `o-teaser-collection__item o-teaser-collection__item--stretched` | Use `o-teaser-collection--numbered` to number the list of teasers in the collection, see an [example in the registry](http://registry.origami.ft.com/components/o-teaser-collection). Use `o-teaser-collection--special` to add a darker background across the full width of the containing relative element, see an [example in the registry](http://registry.origami.ft.com/components/o-teaser-collection). ### Headings To include heading styles output `o-teaser-collection__heading` classes using the `oTeaserCollection` mixin as described above. If your component or project would like to replicate only some parts of the heading style use `oTeaserCollectionContentHeading`. For example, to replicate only the basic heading style pass an empty map: ```scss .my-heading { @include oTeaserCollectionContentHeading($opts: ()); } ``` To replicate the header fully, but without the size modifiers such as `o-teaser-collection__heading--full-width`: ```scss .my-heading { @include oTeaserCollectionContentHeading( $opts: ( 'anchor': true, // Include child anchor styles `.my-heading > a` 'divider': true, // Include the top border styles. 'sizes': () // Do not output size modifiers such as `.my-heading--small`.,,,,,,,, ) ); } ``` `oTeaserCollectionContentHeading` options include: | Key | Possible Values | Description | | ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ | | anchor | Boolean | Output styles for a nested anchor tag, for a collection heading with a link. | | divider | Boolean | Output styles for a divider (border) above the collection heading. | | sizes | 'inverse', 'full-width', 'half-width', 'small' | Output modifier classes for different sizes headings e.g. `my-heading--small`. | ## Migration guide | State | Major Version | Last Minor Release | Migration guide | | :----------: | :-----------: | :----------------: | :---------------------------------------------------: | | ⚠ maintained | 5 | N/A | [migrate to v5](MIGRATION.md#migrating-from-v4-to-v5) | | ╳ deprecated | 4 | 4.2 | [migrate to v4](MIGRATION.md#migrating-from-v3-to-v4) | | ╳ deprecated | 3 | 3.0 | [migrate to v3](MIGRATION.md#migrating-from-v2-to-v3) | | ╳ deprecated | 2 | 2.3 | [migrate to v2](MIGRATION.md#migrating-from-v1-to-v2) | | ╳ deprecated | 1 | 1.2 | - | ## Contact If you have any questions or comments about this component, or need help using it, please either [raise an issue](https://github.com/Financial-Times/o-teaser-collection/issues), visit [#origami-support](https://financialtimes.slack.com/messages/origami-support/) or email [Origami Support](mailto:origami-support@ft.com). --- ## Licence This software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).