Adding a Date Formatter

The DateFormatter class provides flexible date and time formatting capabilities for your Muze visualizations. Whether you're working with full dates, months, quarters, or days of the week, DateFormatter ensures consistent and readable date displays across all chart elements.

Understanding DateFormatter

DateFormatter supports two main formatting modes:

• Custom Format: Use format strings to define your own date display (e.g., "Jan 15, 2024", "2024-01-15")
• Time Index: Automatically format indexed date fields like day of week, month names, or quarters

Basic Syntax

const {
  formatters: { DateFormatter },
} = viz;

// Custom format string
const dateFormatter = new DateFormatter({
  format: "MMM d, yyyy",
});

// Time index (for indexed fields like day of week)
const dayFormatter = new DateFormatter({
  timeIndex: "dayOfWeek",
});

Applying DateFormatter to Axes

/**
 * Available Columns:
 * "Month(Order Date)"
 * "Total Discount"
 */

const {
  muze,
  getDataFromSearchQuery,
  formatters: { DateFormatter },
} = viz;

const orderDateFormatter = new DateFormatter({
  format: "MMM d, yyyy",
});

const data = getDataFromSearchQuery();

muze
  .canvas()
  .rows(["Total Discount"])
  .columns(["Month(Order Date)"])
  .layers([
    {
      mark: "bar",
    },
  ])
  .config({
    axes: {
      x: {
        tickFormat: orderDateFormatter.formatterFunc(),
      },
    },
  })
  .data(data)
  .mount("#chart");

Applying DateFormatter to Tooltips

/**
 * Available Columns:
 * "Month(Order Date)"
 * "Total Discount"
 */

 const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        DateFormatter
    }
} = viz;

const orderDateFormatter = new DateFormatter({
    format: "MMMM d, yyyy"  // Full month name for tooltips
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows(["Total Discount"])
    .columns(["Month(Order Date)"])
    .layers([{
        mark: "bar"
    }])
    .config({t
        interaction: {
            tooltip: {
                fieldFormatters: {
                    "Month(Order Date)": orderDateFormatter.formatterFunc()
                }
            }
        }
    })
    .data(data)
    .mount("#chart");

Applying DateFormatter to Data

/**
 * Available Columns:
 * "Ship Mode"
 * "Month(Order Date)"
 */

const {
  muze,
  getDataFromSearchQuery,
  formatters: { DateFormatter },
} = viz;

const orderDateFormatter = new DateFormatter({
  format: "MM/dd/yyyy",
});

const data = getDataFromSearchQuery();

muze
  .canvas()
  .rows(["Ship Mode"])
  .columns(["Month(Order Date)"])
  .layers([
    {
      mark: "text",
      encoding: {
        text: {
          field: "Month(Order Date)",
          formatter: orderDateFormatter.formatterFunc(),
        },
      },
    },
  ])
  .data(data)
  .mount("#chart");

Applying DateFormatter to Facets

/**
 * Available Columns:
 * "Quarter(Order Date)"
 * "Category"
 * "Ship Mode"
 * --- END ---
 */

const {
  muze,
  getDataFromSearchQuery,
  formatters: { DateFormatter },
} = viz;

const quarterFormatter = new DateFormatter({
  format: "MM/dd/yyyy",
});

const data = getDataFromSearchQuery();

muze
  .canvas()
  .rows([{ field: "Quarter(Order Date)", as: "discrete" }, "Category"])
  .columns(["Ship Mode"])
  .layers([
    {
      mark: "bar",
    },
  ])
  .config({
    rows: {
      facets: {
        formatter: (dataInfo, contextInfo) => {
          return quarterFormatter.format(dataInfo.rawValue);
        },
      },
    },
  })

  .data(data)
  .mount("#chart");

Time Index Formatting

Time index formatting is used when working with indexed date fields (like day of week = 1-7, month = 1-12, quarter = 1-4) instead of full date values.

dayOfWeek

Converts day numbers (1-7) to day names.

const dayFormatter = new DateFormatter({
  timeIndex: "dayOfWeek",
});

// Input: 1 → Output: "Sunday"
// Input: 2 → Output: "Monday"
// Input: 7 → Output: "Saturday"

Example:

/**
 * Available Columns:
 * "Day of Week(Order Date)"
 * "Total Discount"
 * --- END ---
 */

const {
  muze,
  getDataFromSearchQuery,
  formatters: { DateFormatter },
} = viz;

const orderDateFormatter = new DateFormatter({
  timeIndex: "dayOfWeek",
});

const data = getDataFromSearchQuery();

muze
  .canvas()
  .rows(["Total Discount"])
  .columns(["Day of Week(Order Date)"])
  .layers([
    {
      mark: "bar",
    },
  ])
  .config({
    axes: {
      x: {
        tickFormat: orderDateFormatter.formatterFunc(),
      },
    },
    interaction: {
      tooltip: {
        fieldFormatters: {
          "Day of Week(Order Date)": orderDateFormatter.formatterFunc(),
        },
      },
    },
  })
  .data(data)
  .mount("#chart");

monthOfYear

Converts month numbers (1-12) to month names.

const monthFormatter = new DateFormatter({
  timeIndex: "monthOfYear",
});

// Input: 1  → Output: "January"
// Input: 6  → Output: "June"
// Input: 12 → Output: "December"

Example:

/**
 * Available Columns:
 * "MONTH_OF_YEAR(Order Date)"
 * "Total Discount"
 * --- END ---
 */

const {
  muze,
  getDataFromSearchQuery,
  formatters: { DateFormatter },
} = viz;

const orderDateFormatter = new DateFormatter({
  timeIndex: "MonthOfYear",
});

const data = getDataFromSearchQuery();

muze
  .canvas()
  .rows(["Total Discount"])
  .columns(["MONTH_OF_YEAR(Order Date)"])
  .layers([
    {
      mark: "bar",
    },
  ])
  .config({
    axes: {
      x: {
        tickFormat: orderDateFormatter.formatterFunc(),
      },
    },
    interaction: {
      tooltip: {
        fieldFormatters: {
          "MONTH_OF_YEAR(Order Date)": orderDateFormatter.formatterFunc(),
        },
      },
    },
  })
  .data(data)
  .mount("#chart");

quarterOfYear

Converts quarter numbers (1-4) to quarter labels (Q1-Q4).

const quarterFormatter = new DateFormatter({
  timeIndex: "quarterOfYear",
});

// Input: 1 → Output: "Q1"
// Input: 2 → Output: "Q2"
// Input: 4 → Output: "Q4"

Example:

/**
 * Available Columns:
 * "Quarter in Year(Order Date)"
 * "Total Discount"
 * --- END ---
 */

const {
  muze,
  getDataFromSearchQuery,
  formatters: { DateFormatter },
} = viz;

const orderDateFormatter = new DateFormatter({
  timeIndex: "quarterOfYear",
});

const data = getDataFromSearchQuery();

muze
  .canvas()
  .rows(["Total Discount"])
  .columns(["Quarter in Year(Order Date)"])
  .layers([
    {
      mark: "bar",
    },
  ])
  .config({
    axes: {
      x: {
        tickFormat: orderDateFormatter.formatterFunc(),
      },
    },
    interaction: {
      tooltip: {
        fieldFormatters: {
          "Quarter in Year(Order Date)": orderDateFormatter.formatterFunc(),
        },
      },
    },
  })
  .data(data)
  .mount("#chart");