{"id":3041,"date":"2025-07-22T07:25:12","date_gmt":"2025-07-22T11:25:12","guid":{"rendered":"https:\/\/blogs.mathworks.com\/graphics-and-apps\/?p=3041"},"modified":"2025-07-22T07:46:27","modified_gmt":"2025-07-22T11:46:27","slug":"a-guide-to-themes-for-chart-creators-and-app-builders","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/graphics-and-apps\/2025\/07\/22\/a-guide-to-themes-for-chart-creators-and-app-builders\/","title":{"rendered":"A Guide to Themes for Chart Creators and App Builders"},"content":{"rendered":"
\r\n
The long-awaited dark theme is now available in MATLAB R2025a. This article serves as a guide for designing charts and apps in a specific theme or that adapt automatically to either theme. By default, the graphics theme matches the desktop theme, so charts and apps appear in dark or light theme depending on system settings. These preferences can be adjusted in the MATLAB Settings dialog.<\/div>\r\n
Color selection plays a critical role in a themed environment. A color that stands out in light theme may be difficult to see in dark theme. To address this, the default color system in MATLAB graphics is designed to adapt automatically and maintain color contrast across themes. Manually set colors, however, are treated as intentional design choices and do not adapt to theme changes.<\/div>\r\n
This article reviews strategies for managing chart appearance in a themed environment. It includes steps for designing graphical content for a specific theme or for making charts and apps theme-adaptive. For a broader overview of themes in MATLAB, check out Abby Skofield\u2019s recent article, Dark Theme for Plots and Apps<\/a>.<\/div>\r\n

1. Understanding how color properties respond to themes<\/h2>\r\n

Default colors adapt to the figure's current theme<\/h3>\r\n
Color properties that are not manually set use default values. For example, h=plot(magic(3))<\/span> generates three lines with colors defined by the axes' ColorOrder<\/span> property. The ColorMode<\/span> property of these line objects is 'auto'<\/span> which indicates that default colors were assigned to the objects. A key feature of MATLAB Themes is that default colors will update automatically according to the figure's theme.<\/div>\r\n
\"\"<\/div>\r\n
A figure using default colors that adapt to light and dark theme<\/span><\/div>\r\n

Manually set colors are unaffected by the figure's current theme<\/h3>\r\n
When a color property is set manually, it no longer uses the default color value and does not adapt to the figure's theme. For example, h=plot([2 5 4],'-k')<\/span> generates a black line and the line's ColorMode<\/span> property is 'manual'<\/span>. Manually set colors are assumed to be intentional design choices and are unaffected by the figure's theme. If this line is generated in a dark theme, color contrast between the line and the axes background is significantly reduced, making the line nearly invisible. Consider the example below where green lines highlight data labeled as \u201cSuccess\u201d while gray is used to deemphasize data labeled \u201cFail\u201d in light theme (left). Since those colors were manually set, they are preserved when dark theme is applied (right). However, in dark theme, the focus is reversed as gray \u201cFail\u201d data are emphasized while the green \u201cSuccess\u201d data may be difficult to see.<\/div>\r\n
\"\"<\/div>\r\n
Colors chosen for light theme manually applied in dark theme<\/span><\/div>\r\n

Colormaps and Truecolor arrays are unaffected by themes<\/h3>\r\n
Colors determined by a colormap (e.g. surfaces, contours) or a Truecolor array (e.g. images, icons) are not affected by the graphics theme. Exceptions to this rule include some charts that use, by default, the sky<\/span><\/a> colormap in light theme and the abyss<\/span><\/a> colormap in dark theme (e.g. heatmap<\/span>, binscatter<\/span>).<\/div>\r\n

2. Designing charts and apps in a themed environment<\/h2>\r\n
By default, the graphics theme in R2025a is set to match the MATLAB desktop theme which is set to match the system's theme. Desktop and graphics theme defaults can be changed in the settings panel (see Dark Theme for Plots and Apps<\/a>). Since different MATLAB installations may have different preferences, the same chart or app could appear with different themes. I\u2019ll review three recommended strategies for designing charts in a themed environment.<\/div>\r\n
    \r\n \t
  1. Revert manually set colors to use default colors<\/li>\r\n \t
  2. Design charts for a specific theme that is unaffected by preferences<\/li>\r\n \t
  3. Design charts that update manually set colors when the theme changes<\/li>\r\n<\/ol>\r\n

    Strategy 1: Revert manually set colors to default colors<\/h3>\r\n
    Use this strategy when setting color is not necessary.<\/span><\/div>\r\n
    In data visualization, color is often used to convey meaning, perceptual grouping, branding, and aesthetics. Sometimes manual color assignment is applied out of habit, without necessity, or as a result of haphazard copy-pasting. In these cases, the best approach is to find and remove unnecessary color assignments from the code. By removing color assignments, the color properties will revert to default color values which will adapt to the figure's theme.<\/div>\r\n
    To find manual color assignments, look for color definitions in positional input arguments, name-value pairs, or when setting properties on a graphics objects. Simply remove those color definitions. This table shows some common color assignment patterns and how to remove them:<\/div>\r\n \r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n
    \r\n
    Manual color definition<\/span><\/div><\/td>\r\n
    		\r\n
    Default colors<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    text(x, y, string, 'Color'<\/span>, 'k'<\/span>)<\/span><\/div><\/td>\r\n
    		\r\n
    text(x, y, string)<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    figure(Color='white'<\/span>)<\/span><\/div><\/td>\r\n
    		\r\n
    figure()<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    bar(y,'blue'<\/span>)<\/span><\/div><\/td>\r\n
    		\r\n
    bar(y)<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    plot(x,y,'--k'<\/span>)<\/span><\/div><\/td>\r\n
    		\r\n
    plot(x,y,'--'<\/span>)<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    scatter(x,y,size,'black'<\/span>,'filled'<\/span>,'diamond'<\/span>)<\/span><\/div><\/td>\r\n
    		\r\n
    scatter(x,y,size,'filled'<\/span>,'diamond'<\/span>)<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    set(h,'Color'<\/span>,[r g b])<\/span><\/div><\/td>\r\n
    		\r\n
    <delete><\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    h.MarkerFaceColor = [r g b]; <\/span><\/div><\/td>\r\n
    		\r\n
    <delete><\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    h1.Color = h2.Color;<\/span><\/div><\/td>\r\n
    		\r\n
    h1.SeriesIndex = h2.SeriesIndex; <\/span><\/div>\r\n
    *<\/span>Not all objects have a SeriesIndex property<\/span><\/div><\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n
    <\/div>\r\n
    Tip: If you're having trouble finding where a color property is set, call the listener below after the object is created. When the color property is changed, a warning will appear showing where the color property was set. Replace h<\/span> with the variable containing the object handle and replace Color<\/span> with the color property name. In this example, the Color<\/span> property on object h<\/span> was set on line 102 in the script named \"demo\".<\/div>\r\n
    \r\n
    >> addlistener(h,'Color'<\/span>,'PreSet'<\/span>,@(~,~)warning('Color value set.'<\/span>));<\/div>\r\n
    <\/div>\r\n
    Warning: Color value set.<\/div>\r\n
    > In demo>@(~,~)warning('Color value set.'<\/span>)<\/div>\r\n
    In demo (line 102)<\/div>\r\n<\/div>\r\n

    Strategy 2: Design charts and apps for a specific theme unaffected by preferences<\/h3>\r\n
    Use this strategy when designing specifically for light or dark theme.<\/span><\/div>\r\n
    If a chart or app is intended to appear in a particular theme, explicitly set the figure\u2019s Theme<\/span> property. Doing so overrides the graphics theme preference, ensuring the figure always appears as designed. For example, to preserve the appearance of charts created prior to R2025a, set the figure's theme to light<\/span>. In App Designer, set the figure\u2019s Theme property either in the Component Browser or programmatically in the app\u2019s startup function.<\/div>\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n
    \r\n
    Setting the figure's theme property<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    figure(Theme=\"light\"<\/span>)<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    theme(fig, \"dark\"<\/span>)<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    fig.Theme = \"light\"<\/span>;<\/span><\/div><\/td>\r\n<\/tr>\r\n
    \r\n
    set(fig, \"Theme\"<\/span>, \"dark\"<\/span>)<\/span><\/div><\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n
    <\/div>\r\n
    Tip: To preserve compatibility with MATLAB releases prior to R2025a, set the Theme<\/span> property conditionally based on the current MATLAB release. See isMATLABReleaseOlderThan<\/span> (since R2020b) or verLessThan.<\/span><\/div>\r\n
    \r\n
    fig = figure();<\/div>\r\n
    if<\/span> ~verLessThan(\"matlab\"<\/span>,\"25.0\"<\/span>) % R2025a<\/span><\/div>\r\n
    \u00a0\u00a0\u00a0\u00a0theme(fig, \"light\"<\/span>)<\/div>\r\n
    end<\/span><\/div>\r\n<\/div>\r\n

    Strategy 3: Design charts and apps that update manually set colors when the theme changes<\/h3>\r\n
    Use this strategy to support theme-adaptive manually set colors.<\/span><\/div>\r\n
    This strategy is intended for cases where a chart or app should remain visually effective and accessible in both light and dark themes, while using manually assigned colors. This is achieved by programmatically updating color values when the theme changes.<\/div>\r\n
    There are two main approaches, depending on how your chart or app is constructed:<\/div>\r\n
      \r\n \t
    1. For charts and apps created as a collection of graphics or UI objects within a script or apps created in App Designer, use the figure's ThemeChangedFcn<\/span><\/a> callback to update colors in response to theme changes.<\/li>\r\n \t
    2. For custom chart classes built with ChartContainer<\/span><\/a> or custom UI components created with ComponentContainer<\/span><\/a>, use the getTheme<\/span><\/a> method within the container\u2019s update method to set colors for each theme.<\/li>\r\n<\/ol>\r\n
      The following sections walk through the recommended workflow for each approach.<\/div>\r\n

      ThemeChangedFcn<\/span>: for charts and apps created from a collection of graphics objects<\/span> and with App Designer<\/span><\/h4>\r\n
      The ThemeChangedFcn<\/span><\/a> is a callback function introduced on figure objects in R2025a. This callback is invoked when there is a change to the figure's theme. Property values for graphics objects can be updated within the callback function according to the current theme. MATLAB automatically passes two input arguments to the ThemeChangedFcn<\/span>: the first is the figure handle, and the second is a ThemeChangedData<\/span> object generated by the callback event. The Theme<\/span> property of both the figure and the ThemeChangedData<\/span> object returns a GraphicsTheme\u00a0<\/span>object. The GraphicsTheme<\/span> object contains a BaseColorStyle<\/span> property that indicates the figure's current theme as 'dark'<\/span> or 'light'<\/span>. The figure's previous theme is also available in the ThemeChangedData<\/span>. The content of these objects is shown below.<\/div>\r\n
      <\/div>\r\n
      \"\"<\/div>\r\n
      Screenshots of the GraphicsTheme and ThemeChangedData objects<\/span><\/div>\r\n
      With the current theme identified, property values can be updated conditionally within the callback to control manual color assignment in any theme. The example below applies a ThemeChangedFcn<\/span> to a plot depicting Newton\u2019s Law of Cooling. Object handles are stored in a structure h<\/span> for easier function exchange and readability. The structure is passed to the ThemeChangedFcn<\/span> where colors are applied according to the current figure theme (see the full file: NewtonsLawOfCoolingDemo.m<\/a>).<\/div>\r\n
      \r\n
      % Create graphics objects<\/span><\/div>\r\n
      fig = figure();<\/div>\r\n
      hold on<\/span>;<\/div>\r\n
      h = struct(); % Used to store graphics handles<\/span><\/div>\r\n
      <\/div>\r\n
      h.coolingCurve = plot(__, '-'<\/span>, LineWidth=2);<\/div>\r\n
      h.thresholdLine = yline(__, '--'<\/span>, LineWidth=2);<\/div>\r\n
      h.safeHandlingPoint = plot(__, 'o'<\/span>, MarkerSize=8);<\/div>\r\n
      <\/div>\r\n
      <\/div>\r\n
      % Define ThemeChangedFcn<\/span><\/div>\r\n
      fig.ThemeChangedFcn = @(fig,data)updateManualColors(fig, data, h);<\/div>\r\n
      updateManualColors(fig,[],h) % initialize using the current figure theme<\/span><\/div>\r\n
      <\/div>\r\n
      <\/div>\r\n
      function<\/span> updateManualColors(fig,~,h)<\/div>\r\n
      % ThemeChangedFcn: invoked when the theme changes.<\/div>\r\n
      if<\/span> fig.Theme.BaseColorStyle == \"dark\"<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0% Dark theme colors<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.coolingCurve.Color = [0.6 0.7 1]; % lighter blue<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.thresholdLine.Color = [1 0.2 0.2]; % lighter red<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.safeHandlingPoint.MarkerFaceColor = [0 .6 0]; % darker green<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.safeHandlingPoint.MarkerEdgeColor = [0.5 0.8 0.5]; % lighter green<\/span><\/div>\r\n
      else<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0% Light theme colors<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.coolingCurve.Color = [0 0 1]; % blue<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.thresholdLine.Color = [1 0 0]; % red<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.safeHandlingPoint.MarkerFaceColor = [0 1 0]; % green<\/span><\/div>\r\n
      \u00a0\u00a0\u00a0\u00a0h.safeHandlingPoint.MarkerEdgeColor = [0 0.4 0]; % dark green<\/span><\/div>\r\n
      end<\/span><\/div>\r\n
      end<\/span><\/div>\r\n<\/div>\r\n
      The colors that appear in light theme and dark theme are shown below.<\/div>\r\n
      \"\"<\/div>\r\n
      Colors manually set by the ThemeChangedFcn for light and dark themes<\/span><\/div>\r\n
      Other properties that do not participate in themes such as colormaps (e.g., sky, abyss), images, or icons, can also be updated within the callback.<\/div>\r\n

      Chart or app initialization using the <\/span>ThemeChangedFcn<\/span><\/h4>\r\n
      The ThemeChangedFcn<\/span> is only invoked when the figure\u2019s theme changes. When the figure is initialized in the default theme, the ThemeChangedFcn<\/span> is not invoked, so any color assignment within the ThemeChangedFcn<\/span> will not be executed. There are two approaches to ensure the figure is initialized with the manually set colors defined in the ThemeChangedFcn<\/span>.<\/div>\r\n
        \r\n \t
      1. Directly call the <\/span>ThemeChangedFcn<\/span>: Recall that the ThemeChangedFcn<\/span> has two required input arguments: the figure handle and the ThemeChangedData<\/span>, both of which provide access to the figure\u2019s current theme. If the callback function does not use the ThemeChangedData<\/span>, the function can be called directly during the chart setup or from within the app\u2019s startup function. This is demonstrated in the ThemeChangedFcn<\/span> demo above. updateManualColors(fig,[],__)<\/span><\/li>\r\n \t
      2. Trigger the <\/span>ThemeChangedFcn<\/span>: Use this when the ThemeChangedData<\/span> is required. During setup or within an app\u2019s startup function, change the figure\u2019s theme, define the figure\u2019s ThemeChangedFcn<\/span>, and use a cleanup object<\/a> to revert the figure\u2019s ThemeMode<\/span> to \"auto\"<\/span>. Just before setup is complete, the cleanup object will revert the temporary theme change which will trigger the ThemeChangedFcn<\/span>. Here\u2019s what that would look like in the setup method:<\/li>\r\n<\/ol>\r\n
        \r\n
        % revert theme to auto and trigger ThemeChangedFcn upon exiting setup<\/span><\/div>\r\n
        returnInitialTheme = onCleanup(@() theme(fig, \"auto\"<\/span>));<\/div>\r\n
        <\/div>\r\n
        % temporary theme change<\/span><\/div>\r\n
        initialTheme = fig.Theme;<\/div>\r\n
        if<\/span> initialTheme.BaseColorStyle == \"dark\"<\/span><\/div>\r\n
        \u00a0\u00a0\u00a0\u00a0theme(fig, \"light\"<\/span>)<\/div>\r\n
        else<\/span><\/div>\r\n
        \u00a0\u00a0\u00a0\u00a0theme(fig, \"dark\"<\/span>)<\/div>\r\n
        end<\/span><\/div>\r\n
        <\/div>\r\n
        % define ThemeChangedFcn<\/span><\/div>\r\n
        fig.ThemeChangedFcn = @updateManualColors;<\/div>\r\n<\/div>\r\n

        getTheme<\/span>: for chart classes created using <\/span>ChartContainer<\/span> and UI components created using <\/span>ComponentContainer<\/span><\/h4>\r\n
        The matlab.graphics.chartcontainer.ChartContainer<\/span><\/a> and matlab.ui.componentcontainer.ComponentContainer<\/span><\/a> classes are used to create advanced chart objects and custom UI components. These container classes provide an update<\/span> method that is invoked when the chart's theme changes. As a result, there is no need to use the ThemeChangedFcn<\/span> callback when working with classes derived from ChartContainer<\/span> or ComponentContainer<\/span>. Instead, use the getTheme<\/span><\/a> method within the update method to obtain the figure's GraphicsTheme<\/span> object. As described in the previous section, the GraphicsTheme<\/span> object contains a BaseColorStyle<\/span> property indicating the chart's current theme. The update method is also called after the setup<\/span> method which allows for color management at initialization and during any subsequent theme changes.<\/div>\r\n
        The methods block below contains snippets from the setup<\/span> and update<\/span> methods of a SphericalLissajousCurve<\/span> class I created to demonstrate color management for a surface, line, and scatter object that supports both light and dark themes (see the full file: SphericalLissajousCurve.m<\/a>). A spherical Lissajous curve provides uniform and symmetric coverage over a sphere and is used in fields like satellite scanning and orbital mechanics where dark theme may come in handy.<\/div>\r\n