Client Properties

Component client properties can be used to change some behavior of Swing components in FlatLaf. In comparison to UI defaults, which are global and affect all components, client properties can be set on individual components. See JComponent.putClientProperty().

Examples:

myButton.putClientProperty( "JButton.buttonType", "roundRect" );
myScrollPane.putClientProperty( "JScrollBar.showButtons", true );

This documentation uses strings for keys and some values. If you prefer using constants, have a look at interface FlatClientProperties:

myButton.putClientProperty( FlatClientProperties.BUTTON_TYPE, FlatClientProperties.BUTTON_TYPE_ROUND_RECT );
myScrollPane.putClientProperty( FlatClientProperties.SCROLL_BAR_SHOW_BUTTONS, true );

An alternative to using these client properties is to use components from FlatLaf Extras library (see package com.formdev.flatlaf.extras.components), which extend standard Swing components and provide getter and setter methods for these client properties.

JButton / JToggleButton

Key Description Component Value type
JButton.buttonType

Specifies type of a button.

Allowed Values:

  • "square" - Paint the button with square edges (JButton and JToggleButton).
  • "roundRect" - Paint the button with round edges (JButton and JToggleButton).
  • "tab" - Paint the toggle button in tab style (JToggleButton).
  • "help" - Paint a help button (circle with question mark) (JButton).
  • "toolBarButton" - Paint the button in toolbar style (JButton and JToggleButton).

  • "borderless" - Paint the button without a border in unfocused state (JButton and JToggleButton). v1.2

 JButton and JToggleButton

String
JButton.squareSize Specifies whether the button preferred size will be made square (quadratically). JButton and JToggleButton Boolean

JCheckBox

Key Description Component Value type
JButton.selectedState

Specifies selected state of a checkbox.

Allowed Values:

  • "indeterminate" - Paint an indeterminate state on a checkbox.

 JCheckBox

String

JComponent

Key Description Component Value type
FlatLaf.style
v2		 Specifies the style of a component as String in CSS syntax ("key1: value1; key2: value2; ...") or as Map<String, Object> with binary values.

The keys are the same as used in UI defaults, but without component type prefix. E.g. for UI default Slider.thumbSize use key thumbSize.

The syntax of the CSS values is the same as used in FlatLaf properties files, but some features are not supported (e.g. variables). When using a map, the values are not parsed from a string. They must be binary.		 JComponent String or Map<String, Object>
FlatLaf.styleClass
v2		 Specifies the style class(es) of a component as String (single class or multiple classes separated by space characters) or as String[] or List<String> (multiple classes).

The style rules must be defined in UI defaults either as strings (in CSS syntax) or as Map<String, Object> (with binary values). The key must be in syntax: [style]type.styleClass, where the type is optional. E.g. in FlatLaf properties files:		 JComponent String, String[] or List<String> 
[style]Button.primary = borderColor: #08f; background: #08f; foreground: #fff
[style].secondary = borderColor: #0f8; background: #0f8

or in Java code:

UIManager.put( "[style]Button.primary",
               "borderColor: #08f; background: #08f; foreground: #fff" );
UIManager.put( "[style].secondary", "borderColor: #0f8; background: #0f8" );

The rule "Button.primary" can be applied to buttons only. The rule ".secondary" can be applied to any component.

To have similar behavior as in CSS, first the rule without type is applied, then the rule with type. E.g. setting style class to "foo" on a JButton uses rules from UI default keys "[style].foo" and "[style]Button.foo".
JComponent.minimumWidth Specifies minimum width of a component. JButton, JToggleButton, JComboBox, JSpinner and JTextComponent Integer
JComponent.minimumHeight Specifies minimum height of a component. JButton and JToggleButton Integer
JComponent.roundRect Paint the component with round edges. JComboBox, JSpinner, JTextField, JFormattedTextField and JPasswordField Boolean
JComponent.outline

Specifies the outline color of the component border.

Allowed Values:

  • "error" - Paint the component border in another color (usually reddish) to indicate an error.
  • "warning" - Paint the component border in another color (usually yellowish) to indicate a warning.
  • any color (type Color)

  • an array of two colors (type Color[2]) where the first color is for focused state and the second for unfocused state

JButton, JComboBox, JFormattedTextField, JPasswordField, JScrollPane, JSpinner, JTextField and JToggleButton

String or Color or Color[2]
Key Description Component Value type
JComponent.focusOwner Specifies a callback that is invoked to check whether a component is permanent focus owner. Used to paint focus indicators. May be useful in special cases for custom components. JComponent Predicate <JComponent>

Use a java.util.function.Predicate that receives the component as parameter:

myComponent.putClientProperty( "JComponent.focusOwner",
    (Predicate<JComponent>) c -> {
        return ...; // check here
    } );
Key Description Component Value type
Popup.dropShadowPainted Specifies whether a drop shadow is painted if the component is shown in a popup or if the component is the owner of another component that is shown in a popup. JComponent Boolean
Popup.forceHeavyWeight Specifies whether a heavy weight window should be used if the component is shown in a popup or if the component is the owner of another component that is shown in a popup. JComponent Boolean

JProgressBar

Key Description Component Value type
JProgressBar.largeHeight Specifies whether the progress bar has always the larger height even if no string is painted. JProgressBar Boolean
JProgressBar.square Specifies whether the progress bar is paint with square edges. JProgressBar Boolean

JRootPane

Key Description Component Value type
JRootPane.useWindowDecorations
v1.1.1		 Specifies whether FlatLaf native window decorations should be used for JFrame or JDialog. Setting this enables/disables using FlatLaf native window decorations for the window that contains the root pane. This client property has lower priority than system property flatlaf.useWindowDecorations, but higher priority than UI default TitlePane.useWindowDecorations.
(requires Window 10/11)		 JRootPane Boolean
JRootPane.menuBarEmbedded Specifies whether the menu bar is embedded into the window title pane if window decorations are enabled. Setting this enables/disables embedding for the window that contains the root pane. This client property has lower priority than system property flatlaf.menuBarEmbedded, but higher priority than UI default TitlePane.menuBarEmbedded.
(requires Window 10/11)		 JRootPane Boolean
JRootPane.titleBarShowIcon
v2		 Specifies whether the window icon should be shown in the window title bar (requires enabled window decorations). Setting this shows/hides the windows icon for the JFrame or JDialog that contains the root pane. This client property has higher priority than UI default TitlePane.showIcon.
(requires Window 10/11)		 JRootPane Boolean
JRootPane.titleBarBackground
v1.1.2		 Background color of window title bar (requires enabled window decorations).
(requires Window 10/11)		 JRootPane Color
JRootPane.titleBarForeground
v1.1.2		 Foreground color of window title bar (requires enabled window decorations).
(requires Window 10/11)		 JRootPane Color

JScrollBar / JScrollPane

Key Description Component Value type
JScrollBar.showButtons Specifies whether the decrease/increase arrow buttons of a scrollbar are shown. JScrollBar or JScrollPane Boolean
JScrollPane.smoothScrolling Specifies whether the scroll pane uses smooth scrolling. JScrollPane Boolean

JSplitPane

Key Description Component Value type
JSplitPane.expandableSide
v2.2

Specifies what side of the spilt pane is allowed to expand via one-touch expanding arrow buttons. Requires that one-touch expanding is enabled with JSplitPane.setOneTouchExpandable(boolean).

Allowed Values:

  • "left" - Allow expanding only left/top side of the split pane.

  • "right" - Allow expanding only right/bottom side of the split pane.

 JSplitPane

String

JTabbedPane

Key Description Component Value type
JTabbedPane.tabType
v2

Specifies type of the selected tab.

Allowed Values:

  • "underlined" - Paint the selected tab underlined.

  • "card" - Paint the selected tab as card.

 JTabbedPane

String
JTabbedPane.showTabSeparators Specifies whether separators are shown between tabs. JTabbedPane Boolean
JTabbedPane.showContentSeparator Specifies whether the separator between tabs area and content area should be shown. JTabbedPane Boolean
JTabbedPane.hasFullBorder Specifies whether a full border is painted around a tabbed pane. JTabbedPane Boolean
JTabbedPane.hideTabAreaWithOneTab Specifies whether the tab area should be hidden if it contains only one tab. JTabbedPane Boolean
JTabbedPane.minimumTabWidth Specifies the minimum width of a tab. JTabbedPane or tab content components Integer
JTabbedPane.maximumTabWidth Specifies the maximum width of a tab.

Applied only if tab does not have a custom tab component (see JTabbedPane.setTabComponentAt(int,Component)).		 JTabbedPane or tab content components Integer
JTabbedPane.tabHeight Specifies the minimum height of a tab. JTabbedPane Integer
JTabbedPane.tabInsets Specifies the insets of a tab. JTabbedPane or tab content components Insets
JTabbedPane.tabAreaInsets Specifies the insets of the tab area. JTabbedPane Insets
JTabbedPane.tabClosable Specifies whether tabs are closable. If set to true on a tabbed pane component, all tabs in that tabbed pane are closable. To make individual tabs closable, set it to true on a tab content component.

Note that you have to specify a callback (see client property JTabbedPane.tabCloseCallback) that is invoked when the user clicks a tab close button. The callback is responsible for closing the tab.		 JTabbedPane or tab content components Boolean
JTabbedPane.tabCloseToolTipText Specifies the tooltip text used for tab close buttons. JTabbedPane or tab content components String
JTabbedPane.tabCloseCallback Specifies the callback that is invoked when a tab close button is clicked. The callback is responsible for closing the tab.

Either use a java.util.function.IntConsumer that receives the tab index as parameter:		 JTabbedPane or tab content components IntConsumer or BiConsumer <JTabbedPane, Integer> 
myTabbedPane.putClientProperty( "JTabbedPane.tabCloseCallback",
    (IntConsumer) tabIndex -> {
        // close tab here
    } );

Or use a java.util.function.BiConsumer<JTabbedPane, Integer> that receives the tabbed pane and the tab index as parameters:

myTabbedPane.putClientProperty( "JTabbedPane.tabCloseCallback",
    (BiConsumer<JTabbedPane, Integer>) (tabbedPane, tabIndex) -> {
        // close tab here
    } );

If you need to check whether a modifier key (e.g. Alt or Shift) was pressed while the user clicked the tab close button, use EventQueue.getCurrentEvent() to get current event, check whether it is a MouseEvent and invoke its methods. E.g.

AWTEvent e = EventQueue.getCurrentEvent();
boolean shift = (e instanceof MouseEvent) ? ((MouseEvent)e).isShiftDown() : false;
JTabbedPane.tabsPopupPolicy

Specifies the display policy for the "more tabs" button, which shows a popup menu with the (partly) hidden tabs.

Allowed Values:

  • "never" - Display never.

  • "asNeeded" - Display only when needed.

 JTabbedPane

String
JTabbedPane.scrollButtonsPolicy

Specifies the display policy for the forward/backward scroll arrow buttons.

Allowed Values:

  • "never" - Display never.
  • "asNeeded" - Display only when needed. Both scroll arrow buttons are either shown or hidden. Buttons are disabled if scrolling in that direction is not applicable.

  • "asNeededSingle" - Display single button only when needed. If scroll button placement is trailing, then this option is ignored and both buttons are shown or hidden as needed.

 JTabbedPane

String
JTabbedPane.scrollButtonsPlacement

Specifies the placement of the forward/backward scroll arrow buttons.

Allowed Values:

  • "both" - The forward/backward scroll arrow buttons are placed on both sides of the tab area. The backward scroll button at the left/top side. The forward scroll button at the right/bottom side.

  • "trailing" - The forward/backward scroll arrow buttons are placed on the trailing side of the tab area.

 JTabbedPane

String
JTabbedPane.tabAreaAlignment

Specifies the alignment of the tab area.

Allowed Values:

  • SwingConstants.LEADING or "leading" - Align to the leading edge. (default)
  • SwingConstants.TRAILING or "trailing" - Align to the trailing edge.
  • SwingConstants.CENTER or "center" - Align to center.

  • "fill" - Stretch to fill all available space.

 JTabbedPane

Integer or String
JTabbedPane.tabAlignment

Specifies the horizontal alignment of the tab title and icon.

Allowed Values:

  • SwingConstants.LEADING or "leading" - Align to the leading edge.
  • SwingConstants.TRAILING or "trailing" - Align to the trailing edge.

  • SwingConstants.CENTER or "center" - Align to center. (default)

 JTabbedPane or tab content components

Integer or String
JTabbedPane.tabWidthMode

Specifies how the tabs should be sized.

Allowed Values:

  • "preferred" - Tab width is adjusted to tab icon and title. (default)
  • "equal" - All tabs in a tabbed pane has same width.

  • "compact" - Unselected tabs are smaller because they show only the tab icon, but no tab title. Selected tabs show both.

 JTabbedPane

String
JTabbedPane.tabIconPlacement

Specifies the tab icon placement (relative to tab title).

Allowed Values:

  • SwingConstants.LEADING - Place icon left to title. (default)
  • SwingConstants.TRAILING - Place icon right to title.
  • SwingConstants.TOP - Place icon above title.

  • SwingConstants.BOTTOM - Place icon below title.

 JTabbedPane

Integer
JTabbedPane.leadingComponent Specifies a component that will be placed at the leading edge of the tabs area.

For top and bottom tab placement, the laid out component size will be the preferred component width and the tab area height.

For left and right tab placement, the laid out component size will be the tab area width and the preferred component height.		 JTabbedPane Component
JTabbedPane.trailingComponent Specifies a component that will be placed at the trailing edge of the tabs area.

For top and bottom tab placement, the laid out component size will be the available horizontal space (minimum is preferred component width) and the tab area height.

For left and right tab placement, the laid out component size will be the tab area width and the available vertical space (minimum is preferred component height).		 JTabbedPane Component

JTextField

Key Description Component Value type
JTextField.selectAllOnFocusPolicy

Specifies whether all text is selected when the text component gains focus.

Allowed Values:

  • "never" - Never select all text when the text component gains focus.
  • "once" - Select all text when the text component gains focus for the first time and selection was not modified (is at end of text). This is the default.

  • "always" - Always select all text when the text component gains focus.

 JTextField (and subclasses)

String
JTextField.placeholderText Placeholder text that is only painted if the text field is empty. JTextField (and subclasses) or JComboBox String
JTextField.padding
v1.4		 Specifies the padding of the text. This changes the location and size of the text view within the component bounds, but does not affect the size of the component. JTextField (and subclasses) Insets
JTextField.leadingIcon
v2		 Specifies an icon that will be placed at the leading edge of the text field. JTextField (and subclasses) Icon
JTextField.trailingIcon
v2		 Specifies an icon that will be placed at the trailing edge of the text field. JTextField (and subclasses) Icon
JTextField.leadingComponent
v2		 Specifies a component that will be placed at the leading edge of the text field. JTextField (and subclasses) JComponent

The component will be positioned inside and aligned to the visible text field border. There is no gap between the visible border and the component. The laid out component size will be the preferred component width and the inner text field height.

The component should be not opaque because the text field border is painted slightly inside the usually visible border in some cases. E.g. when focused (in some themes) or when an outline color is specified (see client property JComponent.outline).

The component is prepared in the following way:

  • Component client property FlatLaf.styleClass is set to inTextField.
  • If component is a button or toggle button, client property JButton.buttonType is set to toolBarButton and button cursor is set to default cursor (if not set).
  • If component is a toolbar, client property FlatLaf.styleClass is set to inTextField on all toolbar children and toolbar cursor is set to default cursor (if not set).

Because text fields use the text cursor by default and the cursor is inherited by child components, it may be necessary to explicitly set component cursor if you e.g. need the default arrow cursor.
E.g. comp.setCursor( Cursor.getDefaultCursor() ).

Styling is used to modify insets/margins and appearance of buttons and toolbars so that they fit nicely into the text field and do not increase text field height. See styles [style]Button.inTextField and [style]ToolBar.inTextField in Flat[Light|Dark]Laf.properties.
JTextField.trailingComponent
v2		 Specifies a component that will be placed at the trailing edge of the text field.

See JTextField.leadingComponent for details.		 JTextField (and subclasses) JComponent
JTextField.showClearButton
v2		 Specifies whether a "clear" (or "cancel") button is shown on the trailing side if the text field is not empty, editable and enabled. Default is false. JTextField (and subclasses) Boolean
JTextField.clearCallback
v2		 Specifies the callback that is invoked when a "clear" (or "cancel") button is clicked. If a callback is specified than it is responsible for clearing the text field. Without callback, the text field clears itself. JTextField (and subclasses) Runnable or Consumer <JTextComponent>

Either use a Runnable:

myTextField.putClientProperty( "JTextField.clearCallback",
    (Runnable) () -> {
        // clear field here or cancel search
    } );

Or use a java.util.function.Consumer<JTextComponent> that receives the text field as parameter:

myTextField.putClientProperty( "JTextField.clearCallback",
    (Consumer<JTextComponent>) textField -> {
        // clear field here or cancel search
    } );

JToggleButton

Key Description Component Value type
JToggleButton.tab.underlineHeight Height of underline if toggle button type is "tab" (see client property JButton.buttonType). JToggleButton Integer
JToggleButton.tab.underlineColor Color of underline if toggle button type is "tab" (see client property JButton.buttonType). JToggleButton Color
JToggleButton.tab.selectedBackground Background color if selected and toggle button type is "tab" (see client property JButton.buttonType). JToggleButton Color

JTree

Key Description Component Value type
JTree.wideSelection Override if a tree shows a wide selection. Default is true. JTree Boolean
JTree.paintSelection Specifies whether tree item selection is painted. Default is true. If set to false, then the tree cell renderer is responsible for painting selection. JTree Boolean