How to Customize

UI defaults

Many aspects of the FlatLaf look (e.g. colors) are defined in the so-called UI defaults. This is a table where the keys are of type String and the values may have various type (e.g. Color, Border, Insets, etc). The key usually starts with the component type (usually without leading 'J') followed by a dot and the property name. E.g. key Table.background is for the background color of a JTable.

Each theme has its own UI defaults.

There are also "global" UI defaults, which are used for all themes (and other look and feels), that override UI defaults defined by themes. This is useful if you want to customize only few values. You can set them with:

UIManager.put( "someKey", someValue );

If you like to make more changes and/or support multiple themes (light and dark), then it is better to use FlatLaf properties files and benefit from the power of variables, references, color functions, etc.

Also, if you want create an own theme, derived from FlatLaf Light or Dark, properties files are the method of choice.

Types of customizing:

UIManager - simple customization
Application properties files - advanced customization
New theme - create an own theme

UIManager

This is the simplest way to customize FlatLaf and is suitable for small modifications.

UIManager.put( "someKey", someValue );

Invoke Java method UIManager.put() to change FlatLaf UI defaults. Note that this method adds the values into a "global" UI defaults table, which is used for all themes (and also for other look and feels). If your application supports multiple themes or other look and feels, it is better to use application properties files.

Note: Invoke UIManager.put() always after setting the look and feel with e.g. FlatLightLaf.setup() or UIManager.setLookAndFeel() (but before creating the components). Otherwise, the system look and feel is temporary installed before FlatLaf is installed, which may make application startup slower.

Example

Here is an example for doing basic FlatLaf customizing using UIManager:

FlatLightLaf.setup();

UIManager.put( "Component.arc", 0 );
UIManager.put( "ProgressBar.arc", 0 );
UIManager.put( "TabbedPane.selectedBackground", Color.white );

Application properties files

This is the recommended way for applications that use multiple themes or like to do more customization or define own UI defaults (e.g. colors) for own components.

FlatLaf.registerCustomDefaultsSource( "com.myapp.themes" );

Note: Invoke this method before setting the look and feel.

This method registers a package where FlatLaf searches for properties files with custom UI defaults.

This can be used to specify application specific UI defaults that override UI values of existing themes or to define own UI values used in custom components.

There may be multiple properties files in that package for multiple themes. The properties file name must match the used theme class name. E.g. FlatLightLaf.properties for class FlatLightLaf or FlatDarkLaf.properties for class FlatDarkLaf. FlatLaf.properties is loaded first for all themes.

These properties files are loaded after theme (and addon properties) files and therefore can override all UI defaults.

Example

Here is an example for an application that uses light and dark themes, the appearance of some components is changed and application specific colors for light and dark themes are defined.

Create a file com/myapp/themes/FlatLaf.properties used for all themes:

Component.arc = 0
ProgressBar.arc = 0

Create a file com/myapp/themes/FlatLightLaf.properties used for light themes:

TabbedPane.selectedBackground = #fff

# define application specific UI values
MyApp.SideBar.background = darken(@background,10%)
MyApp.someColor = #f00
MyApp.anotherColor = #645554

Create a file com/myapp/themes/FlatDarkLaf.properties used for dark themes:

TabbedPane.selectedBackground = darken($TabbedPane.background,5%)

# define application specific UI values
MyApp.SideBar.background = lighten(@background,10%)
MyApp.someColor = #00f
MyApp.anotherColor = #278354

In your main() method use:

FlatLaf.registerCustomDefaultsSource( "com.myapp.themes" );
FlatLightLaf.setup();

To get application specific UI values in your components use:

Color sideBarBackground = UIManager.getColor( "MyApp.SideBar.background" );

New theme

You can create a new theme by subclassing another theme class and providing a properties file with same basename as the class in the same package as the class.

It is recommended to subclass either FlatLightLaf or FlatDarkLaf (or a subclass of those two classes).

Example

Here is an example for a new theme.

Create a class com/myapp/themes/MyDarkerLaf.java:

package com.myapp.themes;

import com.formdev.flatlaf.FlatDarkLaf;

public class MyDarkerLaf extends FlatDarkLaf {
    public static boolean setup() {
        return setup( new MyDarkerLaf() );
    }

    @Override
    public String getName() {
        return "MyDarkerLaf";
    }
}

Create a file com/myapp/themes/MyDarkerLaf.properties:

@background = #111
@foreground = #ddd
@accentColor = #f57900

In your main() method use:

MyDarkerLaf.setup();

Properties files load order

Properties files are loaded in a well-defined order into a single hash table. Keys defined in later loaded files can therefore override keys defined in earlier loaded files.

The class name of the used look and feel class and its superclasses define the used basenames of the properties files. E.g if you use class FlatDarculaLaf, which extends class FlatDarkLaf that in turn extends class FlatLaf, then FlatDarculaLaf.properties, FlatDarkLaf.properties and FlatLaf.properties are loaded in reverse order. All files are optional.

The properties files are loaded from several places (in this order):

from flatlaf.jar
from JARs that provide the service com.formdev.flatlaf.FlatDefaultsAddon
(e.g. SwingX and JIDE addons).
from packages or folders registered with FlatLaf.registerCustomDefaultsSource()
(see Application Properties)

For example if you use FlatDarculaLaf, the SwingX addon, and also have own properties files in package com.myapp.themes registered with FlatLaf.registerCustomDefaultsSource(), then following properties files are loaded (in this order; all files are optional):

From flatlaf.jar:

com/formdev/flatlaf/FlatLaf.properties
com/formdev/flatlaf/FlatDarkLaf.properties
com/formdev/flatlaf/FlatDarculaLaf.properties

From flatlaf-swingx.jar:

com/formdev/flatlaf/swingx/FlatLaf.properties
com/formdev/flatlaf/swingx/FlatDarkLaf.properties
com/formdev/flatlaf/swingx/FlatDarculaLaf.properties

From myapp.jar:

com/myapp/themes/FlatLaf.properties
com/myapp/themes/FlatDarkLaf.properties
com/myapp/themes/FlatDarculaLaf.properties