Properties Files

Properties files are used in FlatLaf to define UI defaults.

File Format

A .properties file is a text file where each line stores a single property in the format key = value. Leading and trailing white space characters are ignored.

Comment lines start with a # character.

# button colors
Button.background = #ffffff
Button.focusedBackground = #e3f1fa

Keys

A key has the format component.property, where

  • component is the type of the component (usually without leading J)
  • property is the property name

Values

Value types

Following value types are supported:

Primitive Types

Formats of supported primitive types:

  • Boolean - either false and true
  • Integer - one or more decimal digits 0-9; first character may be minus sign '-' or a plus sign '+'
  • Float - zero or more decimal digits 0-9 followed by a dot character '.' followed by one or more decimal digits; first character may be minus sign '-' or a plus sign '+'
  • String - start with a '"' character followed by any character and end with a '"' character
  • null - must be null
# boolean
Menu.opaque = false
MenuItem.borderPainted = true

# integer
Button.borderWidth = 1

# float
Popup.dropShadowOpacity = 0.15

# null
Menu.checkIcon = null

Color

Colors (java.awt.Color) are specified in hexadecimal formats #RRGGBB, #RRGGBBAA, #RGB or #RGBA. R (red), G (green), B (blue) and A (alpha) are hexadecimal characters (0-9, a-f, A-F). The characters of the two short formats are doubled. E.g. #f26 is the same as #ff2266. Likewise #0f38 is the same as #00ff3388.

Button.background = #fff
Button.focusedBackground = #e3f1fa
PasswordField.capsLockIconColor = #00000064

Use color functions to derive colors from already defined colors to reduce the number of individual colors. E.g.:

TableHeader.separatorColor = darken($TableHeader.background,10%)

Font since v2

Fonts (java.awt.Font) are in format [normal] [bold|+bold|-bold] [italic|+italic|-italic] [<size>|+<incr>|-<decr>|<percent>%] [family[, family ...]] [$baseFontKey]

The font is either derived from the default font (key defaultFont) or from font $baseFontKey. All parameters are optional. If not specified, it is used from the default/base font.

normal, bold and italic specify the font style/weight and replace the style of the default/base font. +bold, -bold, +italic and -italic add/remove a style to/from the style of the default/base font.

<size> specifies the font size. +<incr> or -<decr> increase or decrease the font size of the default/base font. When the UI is scaled, then these values are also scaled. <percent>% specify the font size relative to the default/base font.

family[, family ...] specify one or more font families. If a family is not available, then the next family is used. If none of the families are available, the family of the default/base font is used. If a family name contains spaces, enclose it in " or '.

$baseFontKey specifies the base font. If not given, the default font is used as base font.

defaultFont = 13 "Open Sans", "Noto Sans", Roboto, Arial
Label.font = +italic
h1.font = +12
xxxl.font = bold +36
lightTitle.font = 200% $light.font

There are several predefined font styles that you can use for headings or smaller text. See Typography.

Insets

Insets (java.awt.Insets) are in format top,left,bottom,right, where each of the four parameters must be of type integer.

Button.margin = 2,14,2,14
TabbedPane.tabInsets = 0,12,0,12

Dimension

Dimensions (java.awt.Dimension) are in format width,height, where each of the two parameters must be of type integer.

DesktopIcon.iconSize = 64,64
ProgressBar.horizontalSize = 146,4

Border

Borders (javax.swing.border.Border) are either in format top,left,bottom,right[,lineColor[,lineThickness[,arc]]] or fullQualifiedClassName.

The first format creates a border with the given insets top,left,bottom,right. An empty border is created if no lineColor is specified. A line border is created if (optional) lineColor is specified. Line thickness is either (optional) lineThickness or 1. Arc diameter since v2 (for rounded rectangle) is either (optional) arc or 0.

OptionPane.border = 12,12,12,12
ToolTip.border = 4,6,4,6,#000

The second format creates a border with the given full qualified class name fullQualifiedClassName. The class must be public and must have a zero-argument public constructor. A single instance of the border is created lazy (when first used) and its constructor can query values from the UI defaults with UIManager.get(String key).

Button.border = com.formdev.flatlaf.ui.FlatButtonBorder

Icon

Icons (javax.swing.Icon) are in format fullQualifiedClassName. The class must be public and must have a zero-argument public constructor. A single instance of the icon is created lazy (when first used) and its constructor can query values from the UI defaults with UIManager.get(String key).

CheckBox.icon = com.formdev.flatlaf.icons.FlatCheckBoxIcon

Gray Filter

Gray filter (com.formdev.flatlaf.util.GrayFilter) is in format brightness,contrast,alpha.

Parameters:

  • brightness - an integer in range -100 - 100 where 0 has no effect
  • contrast - an integer in range -100 - 100 where 0 has no effect
  • alpha - an integer in range 0-100 where 0 is transparent, 100 has no effect
Component.grayFilter = 25,-25,100

Variables

Variables are defined in properties files and can only be used within other values in properties files. They are not added to the UI defaults and therefore you can not query them with UIManager.get(String key).

Variables are defined in the same way as properties, but the key starts with a '@' character:

@background = #f2f2f2
@foreground = #000
@menuHoverBackground = darken(@menuBackground,10%,derived)

Usage of variables:

Table.background = @background
Table.foreground = @foreground
MenuBar.hoverBackground = @menuHoverBackground
MenuItem.acceleratorForeground = lighten(@foreground,30%)

References

References to other properties can be used in property values. They start with a '$' character followed be the referenced key.

Table.background = $List.background
Tree.background = $List.background
Button.hoverBackground = darken($Button.background,3%,derived)

Wildcard replacements

Keys starting with *. are wildcard replacements. They replace all matching keys defined in javax.swing.plaf.basic.BasicLookAndFeel.getDefaults() and FlatLaf.getDefaults(). This is used to initialize basic component colors.

*.background = #f2f2f2
*.foreground = #000

Platform specific values

If a key is preceded by [win], [mac] or [linux], then its value is only used on the given platform.

[win]Button.defaultButtonFollowsFocus = true
[mac]OptionPane.isYesLast = true
[linux]ScrollBar.minimumThumbSize = 18,18

Light/dark theme specific values

If a key is preceded by [light] or [dark], then its value is only used if the current FlatLaf theme is light or dark. Method com.formdev.flatlaf.FlatLaf.isDark() is used to detect whether a theme is light or dark.

[light]Button.background = #fff
[dark]Button.background = #000

Scaled values

FlatLaf has built-in scaling for HiDPI screens. This is disabled if Java does the scaling itself (Java 9 and later). On Java 8 (and Linux), FlatLaf scales in Java code where necessary by invoking method UIScale.scale(). Sometimes this is not possible because a UI value is used in Java core classes. In this case it is necessary to specify in the properties file that a value should be scaled when used.

Following value types can be scaled in properties files:

  • integer - prefix value with {scaledInteger}
  • float - prefix value with {scaledFloat}
  • Insets - prefix value with {scaledInsets}
  • Dimension - prefix value with {scaledDimension}
Caret.width = {scaledInteger}1
Component.innerFocusWidth = {scaledFloat}0.5
TabbedPane.tabInsets = {scaledInsets}0,12,0,12
ColorChooser.swatchesSwatchSize = {scaledDimension}16,16

Type prefix

In case that the value type can not be detected correctly, it is necessary to explicitly specify it by prefixing the value with one of the following strings:

{integer}, {float}, {string}, {character}, {color}, {font}, {insets}, {dimension}, {border}, {icon} or {grayFilter}

Component.innerOutlineWidth = {float}1
Table.intercellSpacing = {dimension}0,0

Value type detection

Because properties files are text files, but UI default values must be binary, it is necessary to convert them. Following strategy is used to convert value strings:

  1. strings false and true are converted to Boolean
  2. string null becomes Java null
  3. strings starting with '#' character become Colors
  4. strings starting with a type prefix use the specified type
  5. if key ends with
  6. strings starting and ending with '"' character become Java Strings
  7. if string is parsable as Color, Integer or Float, use it
  8. use string as Java String

General Functions

Available general functions:

  • if - Checks a condition and returns one of two values.
  • lazy - Get value from another UI property lazy (on first use).

if

Checks a condition and returns one of two values.

Syntax: if(condition,trueValue,falseValue)

Parameters:

  • condition - evaluates to true if:
    • is not null
    • is not false
    • is not an integer with zero value
  • trueValue - used if condition is true
  • falseValue - used if condition is false
@accentSliderColor = if(@accentColor, @accentColor, @accentBase2Color)

If @accentColor is defined (is not null), then it is used. Otherwise @accentBase2Color is used.

lazy

Get value from another UI property lazy (on first use). This is useful to reference UI properties that are not stored in properties files. E.g. predefined action or object colors.

Syntax: lazy(uiKey)

Parameters:

  • uiKey - UI key, which value should be used
PasswordField.revealIconColor = lazy(Actions.Grey)

Color Functions

Color functions create new colors either by modifying existing colors or by defining new colors in RGB or HSL color space.

Using color modification functions makes it easy to define colors that are e.g. lighter or darker than already used colors. This reduces the number of individual colors and makes it easy to change themes by modifying base colors.

Available color functions:

  • lighten - Increase the lightness of a color in HSL color space.
  • darken - Decrease the lightness of a color in HSL color space.
  • saturate - Increase the saturation of a color in HSL color space.
  • desaturate - Decrease the saturation of a color in HSL color space.
  • fadein - Increase the opacity (alpha) of a color.
  • fadeout - Decrease the opacity (alpha) of a color.
  • fade - Set the opacity (alpha) of a color.
  • spin - Rotate hue angle of a color.
  • changeHue - Sets hue of a color to a new value.
  • changeSaturation - Sets saturation of a color to a new value.
  • changeLightness - Sets lightness of a color to a new value.
  • changeAlpha - Sets alpha of a color to a new value.
  • mix - Mix two colors together in variable proportion.
  • tint - Mix color with white in variable proportion.
  • shade - Mix color with black in variable proportion.
  • contrast - Choose which of two colors provides the greatest contrast with another.
  • rgb - Creates an opaque color from red, green and blue (RGB) values.
  • rgba - Creates transparent a color from red, green, blue (RGB) and alpha values.
  • hsl - Creates an opaque color from hue, saturation and lightness (HSL) values.
  • hsla - Creates transparent a color from hue, saturation, lightness (HSL) and alpha values.

lighten / darken

Increase or decrease the lightness of a color in HSL color space (alternatively use tint / shade).

Syntax: lighten(color,amount[,options]) or darken(color,amount[,options])

Parameters:

  • color - base color (e.g. #f00), a color function or a reference to another color value
  • amount - percentage 0-100% that is added to (lighten) or removed from (darken) the lightness (absolute)
  • options - optional options (separate multiple options with space characters):
    • relative - specifies that the amount is relative to the lightness of the base color, so adding 10% to a 20% lightness results in 22%
    • autoInverse - specifies that the amount should be inverted if the lightness of the base color is greater than 65% (lighten) or less than 35% (darken); this option is automatically enabled if option derived is enabled, except if option noAutoInverse is enabled
    • derived - specifies that the real color is computed at runtime based on a variable base color (usually the current background color of a component); this works only for a limited set of UI keys
    • lazy- specifies that the color is computed lazy (when first used); in this case, the color parameter must be a UI key (without leading '$') that is used to get the base color

Examples:

#80e619 → #b3f075   lighten(#80e619,20%) → #b3f075

#80e619 → #4d8a0f   darken(#80e619,20%) → #4d8a0f

Button.background = darken(#ffffe1,80%)
Button.foreground = lighten(#ff0,50%,relative)
Button.hoverBackground = lighten($Button.background,3%,derived)
InternalFrame.closePressedBackground = darken(Actions.Red,10%,lazy)
Component.warning.borderColor = lighten(saturate($Component.warning.focusedBorderColor,25%),20%)

saturate / desaturate

Increase or decrease the saturation of a color in HSL color space.

Syntax: saturate(color,amount[,options]) or desaturate(color,amount[,options])

The parameters are the same as in lighten / darken functions.

Examples:

#80e619 → #80ff00   saturate(#80e619,20%) → #80ff00

#80e619 → #80cd32   desaturate(#80e619,20%) → #80cd32

Component.error.borderColor = desaturate($Component.error.focusedBorderColor,25%)
Component.custom.borderColor = desaturate(#f00,50%,relative derived noAutoInverse)

fadein / fadeout

Increase or decrease the opacity (alpha) of a color.

Syntax: fadein(color,amount[,options]) or fadeout(color,amount[,options])

The parameters are the same as in lighten / darken functions.

fade

Set the opacity (alpha) of a color.

Syntax: fade(color,amount[,options])

Parameters:

  • color - base color (e.g. #f00), a color function or a reference to another color value
  • amount - percentage 0-100%
  • options - optional options:
    • derived - specifies that the real color is computed at runtime based on a variable base color (usually the current background color of a component); this works only for a limited set of UI keys
    • lazy since v2 - specifies that the color is computed lazy (when first used); in this case, the color parameter must be a UI key (without leading '$') that is used to get the base color
Slider.focusedColor = fade($Component.focusColor,50%,derived)

spin

Rotate hue angle of a color.

Syntax: spin(color,angle[,options])

Parameters:

  • color - base color (e.g. #f00), a color function or a reference to another color value
  • angle - number of degrees to rotate (+ or -)
  • options - optional options:
    • derived - specifies that the real color is computed at runtime based on a variable base color (usually the current background color of a component); this works only for a limited set of UI keys

Examples:

#f2330d → #f2a50d   spin(#f2330d,30) → #f2a50d

#f2330d → #f20d5a   spin(#f2330d,-30) → #f20d5a

changeHue / changeSaturation / changeLightness / changeAlpha since v1.6

Sets hue/saturation/lightness/alpha of a color to a new value.

Syntax: changeHue(color,value[,options]) or changeSaturation(color,value[,options]) or changeLightness(color,value[,options]) or changeAlpha(color,value[,options])

Parameters:

  • color - base color (e.g. #f00), a color function or a reference to another color value
  • value - for hue: number of degrees (0-360); otherwise: percentage 0-100%
  • options - optional options:
    • derived - specifies that the real color is computed at runtime based on a variable base color (usually the current background color of a component); this works only for a limited set of UI keys

Examples:

#80e619 → #c4e619   changeHue(#80e619,70) → #c4e619

#80e619 → #80cc33   changeSaturation(#80e619,60%) → #80cc33

#80e619 → #b3f075   changeLightness(#80e619,70%) → #b3f075

Button.focusedBackground = changeLightness($Component.focusColor,95%)

mix since v1.6

Mix two colors together in variable proportion.

Syntax: mix(color1,color2[,weight])

Parameters:

  • color1 - color (e.g. #f00), a color function or a reference to another color value
  • color2 - color (e.g. #f00), a color function or a reference to another color value
  • weight - the weight (in range 0-100%) to mix the two colors (default is 50%); larger weight uses more of first color, smaller weight more of second color

Examples:

#ff0000 + #0000ff → #800080   mix(#ff0000, #0000ff, 50%) → #800080

TabbedPane.focusColor = mix(@selectionBackground,$TabbedPane.background,10%)

tint / shade since v1.6

Mix color with white (tint) or black (shade) in variable proportion.
These functions are good alternatives to lighten / darken.

tint(color,weight) is the same as mix(#fff,color,weight).
shade(color,weight) is the same as mix(#000,color,weight).

Syntax: tint(color[,weight]) or shade(color[,weight])

Parameters:

  • color - color (e.g. #f00), a color function or a reference to another color value
  • weight - the weight (in range 0-100%) to mix the two colors (default is 50%); larger weight uses more of first color, smaller weight more of second color

Examples:

#ff00ff → #ff80ff   tint(#ff00ff, 50%) → #ff80ff

#ff00ff → #800080   shade(#ff00ff, 50%) → #800080

@disabledForeground = tint(@foreground,55%)
@icon = shade(@background,27%)
Component.borderColor = shade(@background,20%)
Component.disabledBorderColor = tint($Component.borderColor,20%)

contrast since v2

Choose which of two colors provides the greatest contrast with another. E.g. useful to choose a text color that is readable for a background color. The colors are compared using their gamma-corrected luma value, not their lightness.

Syntax: contrast(color,dark,light[,threshold])

Parameters:

  • color - a color to compare against
  • dark - a designated dark color (e.g. #000)
  • light - a designated light color (e.g. #fff)
  • threshold - the threshold (in range 0-100%) to specify where the transition from dark to light is (default is 43%)

Examples:

#bbb #00f #0f0 → #00f : Text   contrast(#bbb, #00f, #0f0) → #00f

#444 #00f #0f0 → #0f0 : Text   contrast(#444, #00f, #0f0) → #0f0

@selectionForeground = contrast(@selectionBackground, @foreground, #fff)

rgb / rgba

Creates a color from red, green, blue (RGB) and alpha (optional) values.

Syntax: rgb(red,green,blue) or rgba(red,green,blue,alpha)

Parameters:

  • red - an integer 0-255 or a percentage 0-100%
  • green - an integer 0-255 or a percentage 0-100%
  • blue - an integer 0-255 or a percentage 0-100%
  • alpha - an integer 0-255 or a percentage 0-100%

Examples:

#5a8120   rgb(90, 129, 32) → #5a8120

Button.focusedBackground = rgb(227,241,250)
PasswordField.capsLockIconColor = rgba(0,0,0,120)

hsl / hsla

Creates a color from hue, saturation, lightness (HSL) and alpha (optional) values.

Syntax: hsl(hue,saturation,lightness) or hsla(hue,saturation,lightness,alpha)

Parameters:

  • hue - an integer 0-360 representing degrees
  • saturation - a percentage 0-100%
  • lightness - a percentage 0-100%
  • alpha - a percentage 0-100%

Examples:

#7fff00   hsl(90, 100%, 50%) → #7fff00

List.selectionBackground = hsl(209,66%,44%)
List.selectionForeground = hsla(0,0%,100%,50%)