Understanding the @ConditionalOnProperty Annotation in Spring Boot

One of the many advantages of the Spring Boot framework is its vast collection of annotations that simplify the configuration and bootstrapping process of Spring applications. Among these annotations, the @ConditionalOnProperty has gotten attention due to its utility in conditional bean creation based on property values.

1. Introduction to Conditional Configuration

Before understanding @ConditionalOnProperty, it's important to understand the concept of conditional configuration in Spring Boot. Sometimes, in the lifecycle of a project, developers may find a need to load specific beans or configurations only under certain conditions. This is where Spring Boot’s conditional annotations come into play. They help in controlling which beans get loaded based on conditions.

2. The Role of @ConditionalOnProperty

The primary purpose of @ConditionalOnProperty is to conditionally create a bean based on a particular property's value in the application's properties or YAML files.

For instance, consider a situation where an application has a feature that should be activated only if a specific property is set. Rather than having complex if-else code or additional configuration setups, the @ConditionalOnProperty annotation can handle this elegantly.

3. How to Use @ConditionalOnProperty

A typical usage of the @ConditionalOnProperty annotation might look like this:

@ConditionalOnProperty(name = "feature.x.enabled", havingValue = "true")
public class FeatureXService {
    //... Your service methods

In the above code snippet:

  • name refers to the property's name.

  • havingValue is the value of the property that should match for the bean to be created. In this case, the FeatureXService bean will be instantiated only if the feature.x.enabled property in the application's properties or YAML file has a value of true.

4. Extended Attributes

Besides name and havingValue, the annotation also offers:

  • matchIfMissing: This is a boolean value which, if set to true, will create the bean if the property is absent in the configuration file.

  • prefix: This can be used to group property names if they share the same prefix.

5. Real-world Scenarios

Imagine a system that integrates with various third-party services, like payment gateways, message brokers, or notification services. Depending on the deployment environment or client preferences, certain services might be enabled or disabled. Using the @ConditionalOnProperty annotation, developers can easily turn on or off these services based on the configuration properties.

a. Basic Matching

Given an application.properties:


Your service class with the basic match will look like:

@ConditionalOnProperty(name = "feature.x.enabled", havingValue = "true")
public class FeatureXService {
    //... Your service methods

Here, FeatureXService is instantiated only when feature.x.enabled is set to true.

b. Using the matchIfMissing Attribute

Imagine you want a bean to be instantiated by default unless explicitly turned off:


The service class:

@ConditionalOnProperty(name = "feature.y.enabled", matchIfMissing = true)
public class FeatureYService {
    //... Your service methods

In this scenario, if feature.y.enabled is not defined in the properties file, the bean will still be created due to matchIfMissing = true. However, in our example property, since it's explicitly set to false, the bean will not be created.

c. Using the prefix Attribute

For a configuration with a shared prefix, e.g.,


Your service class would look like:

@ConditionalOnProperty(prefix = "app.feature", name = "z.enabled", havingValue = "true")
public class FeatureZService {
    //... Your service methods

The prefix helps in grouping properties with shared initial segments, providing cleaner and more organized code.

d. Conditional Configuration for Database Beans

Imagine you have two types of databases, and you wish to switch between them based on a property:


You can conditionally load beans as:

public class DatabaseConfig {

    @ConditionalOnProperty(name = "database.type", havingValue = "MYSQL")
    public DatabaseService mySqlDatabaseService() {
        return new MySqlDatabaseService();

    @ConditionalOnProperty(name = "database.type", havingValue = "MONGODB")
    public DatabaseService mongoDatabaseService() {
        return new MongoDatabaseService();

This setup ensures that the appropriate database service bean gets loaded based on the configured database type.


The versatility of the @ConditionalOnProperty annotation is evident from the varied scenarios where it can be applied. These hands-on examples not only showcase its practicality but also how seamlessly it integrates into the Spring Boot environment. By understanding these intricacies, developers can create flexible, easily configurable, and maintainable Spring Boot applications.

Did you find this article valuable?

Support Adrian Kodja by becoming a sponsor. Any amount is appreciated!