Origami Frontend Components & Services

Readme: o-topper

o-topper has a support status of "experimental". This means that the component's API may change without notice, and there is no guarantee that the component is ready for production use.

This component is for displaying header sections at the top of articles

v1 Usage Warning

Use of this component is not recommended outside FT.com / app.ft.com. The Javascript helper which currently extracts themes, colors, and other topper display data is deeply tied to the FT.com content store and includes hardcoded UUIDs and business logic. In future this will be moved into another layer of the FT.com stack, and the new configuration used to control topper display and functionality will be documented, at which stage this topper will be more suitable for wider use.



The basic markup structure for a topper will look something like this:

<div class="o-topper o-topper--basic o-topper--color-paper">
    <div class="o-topper__content">
        <div class="o-topper__tags">
            <a href="https://www.ft.com/german-election" class="o-topper__topic">German election</a>
        <h1 class="o-topper__headline">
            Merkel reaches ‘grand coalition’ breakthrough with Social Democrats
        <div class="o-topper__standfirst">Move raises hopes of end to political deadlock that has gripped Germany since September</div>

    <div class="o-topper__background"></div>

Toppers support a wide array of elements and can be customised using several themes and background colors. For a full list of examples, including example markup, see o-topper in the Registry.

Supported elements

Element Use case
.o-topper__content Main content area of topper. Required parent of all elements except __visual and __background.
.o-topper__tags Wrapper element for the article concept tag elements __brand, __topic and __opinion-genre.
.o-topper__brand A concept tag that represents a brand, e.g. "The Big Read".
.o-topper__topic A concept tag that represents a topic or generic concept.
.o-topper__opinion-genre A concept tag that represents the abstract Opinion genre.
.o-topper__columnist Wrapper element for __columnist-name. Should be placed below the headline and standfirst.
.o-topper__columnist-name Represents the columnist that wrote an Opinion genre article.
.o-topper__headline The main headline of the article.
.o-topper__standfirst A short introduction to the article.
.o-topper__background Element used to display the editorially-chosen colored background of the topper. Must be empty.
.o-topper__visual Wrapper for the visual elements __picture and __image. Should be a <figure> tag.
.o-topper__picture A <picture> tag visual element.
.o-topper__image An <img> tag visual element, usually used as fallback for a <picture>.
.o-topper__image-credit Element showing credit/copyright for the __picture or __image. Should be a <figcaption> tag.


These themes affect the layout and visual style of all elements. See the demos for examples.



These colors affect the background of the .o-topper__background and .o-topper__visual elements, and select a contrasting text color for all other elements. See o-colors for examples of the colors.



As with all Origami components, o-topper has a silent mode. To use its compiled CSS (rather than incorporating its mixins into your own Sass) set $o-topper-is-silent : false; in your Sass before you import the o-topper Sass:

$o-topper-is-silent: false;
@import 'o-topper/main';

Using Sass mixins


This component includes a Javascript helper, which should be used to select the correct topper themes and colors, as well as other topper-overriden data, given a particular JSON-formatted FT article (such as from the Content API).

const {mapContentToTopper} = require('o-topper');

const topper = mapContentToTopper(ftArticle);

Topper data

Data returned by the topper helper should be used in the product's templates. Other keys may be returned but should not be relied on as documented behaviour.

Key Usage
headline Should be used in place of the standard article headline
standfirst Should be used in place of the standard article standfirst
modifiers Should be included as o-topper--[modifier] classes on the o-topper wrapper element
backgroundColor Should be included as an o-topper--color-[color] class on the wrapper element
themeImageRatio Used to differentiate split and full-bleed topper images
includesImage Use to disable main article image to prevent duplicate images when topper includes one
largeHeadline Indicates whether to use o-topper__headline--large on o-topper__headline


If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #ft-origami or email Origami Support.


This software is published by the Financial Times under the MIT licence.

experimental Origami v1
Switch component view

GitHub Repository

Install o-topper

If using the Build Service, add o-topper@^2.7.2 to your script and link tags.

If running a Manual Build, run npm install "o-topper@^2.7.2".

Help & Support

o-topper is maintained directly by the Origami team. If you have any questions about o-topper or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com