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).

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
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]

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
(since 1.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)
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)
JRootPane Boolean
JRootPane.titleBarBackground
(since 1.1.2)
Background color of window title bar (requires enabled window decorations).
(requires Window 10)
JRootPane Color
JRootPane.titleBarForeground
(since 1.1.2)
Foreground color of window title bar (requires enabled window decorations).
(requires Window 10)
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

JTabbedPane

Key Description Component Value type
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. JTabbedPane or tab content components IntConsumer or BiConsumer <JTabbedPane, Integer>

Either use a java.util.function.IntConsumer that receives the tab index as parameter:

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 layed out component size will be the preferred component width and the tab area height.

For left and right tab placement, the layed 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 layed 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 layed 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

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