Out-of-the-box components
Remarkable Pro
Customizations
Comparison ranges

Comparison period overrides

Theme namespace: theme.defaults.comparisonPeriodsOptions

Comparison periods are closely related to date ranges. Components like the Comparison Period Select Field display options such as:

  • Previous period
  • Previous month
  • Same period last year
  • etc.

These default options are defined within Remarkable’s default theme, but you can easily override them to:

  • hide or re-order options
  • change how comparison ranges are calculated
  • add entirely new comparison options

This lets you model comparison logic in a way that matches your product and your users’ expectations.

Modifying the default options

You configure comparison period options via the theme at:

theme.defaults.comparisonPeriodsOptions

Each option has the following shape:

type TimeRange = {
  from?: Date; // UTC
  to?: Date;   // UTC
};
 
type ComparisonPeriodOption = {
  value: string;                     // e.g. 'previous-period'
  label: string;                     // e.g. 'defaults.comparisonPeriodOptions.previousPeriod | Previous period'
  dateFormat: string;                // e.g. 'DD MMM YYYY'
  getRange: (timeRange: TimeRange) => TimeRange; // how the comparison range is calculated
};

You can access the defaults from the parentTheme like so:

 
// embeddable.theme.ts
 
const themeProvider = (clientContext: any, parentTheme: Theme): Theme => {
 
  const myTheme = {
    defaults: {
      comparisonPeriodsOptions: parentTheme.defaults.comparisonPeriodsOptions,
    },
  };
 
  return defineTheme(parentTheme, myTheme) as Theme;
};

Things to notice

  • The default list is just an array of ComparisonPeriodOption, so you can manipulate it using normal array utilities like filter, map, sort, concat, etc.
  • getRange takes a single dateRange: TimeRange argument. This is the primary date range (for example, “This month”), and getRange returns the comparison range.
    • For example, if dateRange represents today and the comparison period is “Previous period”, then getRange(dateRange) should return yesterday as a TimeRange.

Example: re-order the default options

Here’s a simple example that changes the order of the options (for example, putting Previous month first):

// embeddable.theme.ts
 
const themeProvider = (clientContext: any, parentTheme: Theme): Theme => {
  const defaults = parentTheme.defaults.comparisonPeriodsOptions;
 
  const myOptions = [
    // ensure 'previous-month' goes first if it exists
    ...defaults.filter((option) => option.value === 'previous-month'),
    // then everything else
    ...defaults.filter((option) => option.value !== 'previous-month'),
  ];
 
  const myTheme = {
    defaults: {
      comparisonPeriodsOptions: myOptions,
    },
  };
 
  return defineTheme(parentTheme, myTheme) as Theme;
};

Example: change the default options

Here’s how we might edit the Previous period option, changing:

  • its label
  • how the comparison range is calculated
 
// embeddable.theme.ts
 
const themeProvider = (clientContext: any, parentTheme: Theme): Theme => {
  const myOptions = parentTheme.defaults.comparisonPeriodsOptions.map((option) => {
    if (option.value === 'previous-period') {
      return {
        ...option,
        label: 'defaults.comparisonPeriodOptions.priorPeriod | Prior period',
        getRange: (dateRange: TimeRange): TimeRange => {
          // custom function that returns a TimeRange
        },
      };
    }
 
    return option;
  });
 
  const myTheme: DeepPartial<Theme> = {
    defaults: {
      comparisonPeriodsOptions: myOptions,
    },
  };
 
  return defineTheme(parentTheme, myTheme) as Theme;
};

Example: add a new option

Let’s say we want to add a new comparison period: “2 years ago”.

All we need to do is append a new ComparisonPeriodOption to the existing list:

 
// embeddable.theme.ts
 
const themeProvider = (clientContext: any, parentTheme: Theme): Theme => {
  const myOptions: ComparisonPeriodOption[] = [
    ...parentTheme.defaults.comparisonPeriodsOptions,
    {
      value: 'two-years-ago',
      label: 'customOptions.twoYearsAgo | Two years ago',
      dateFormat: 'DD MMM YYYY',
      getRange: (dateRange: TimeRange): TimeRange => {
        return myCustomPeriodFunction(dateRange); // must return a UTC-based TimeRange
      },
    },
  ];
 
  const myTheme: DeepPartial<Theme> = {
    defaults: {
      comparisonPeriodsOptions: myOptions,
    },
  };
 
  return defineTheme(parentTheme, myTheme) as Theme;
};

Things to notice

  • Comparison ranges should be returned in UTC. Remarkable Pro handles the timezone conversion for display.
  • The dateFormat controls how the comparison dates are rendered in the UI.

Making new options appear in the Builder

  • When you add a new comparison period option, it will automatically appear in any Remarkable Pro (or custom) components that use comparisonPeriodsOptions, such as the Comparison Period Select Field.
  • If you want the new option to appear in Embeddable’s Builder as well (for example, to select it as a default comparison setting), you’ll also need to extend Embeddable’s custom comparison period type (e.g. ComparisonPeriodType). Learn more about defining custom types here.
  • View the Comparison Period custom type in the Remarkable library here (opens in a new tab).
Date rangesChart overrides