Introduction

In Spring Boot, creating a bean conditionally based on configuration is common, but the easiest way is usually not to inspect the @ConfigurationProperties object itself. Conditions are evaluated early during configuration, so the standard solution is to read the raw property through @ConditionalOnProperty or a custom Condition, then bind the same property into @ConfigurationProperties for normal use.

The Simplest Solution: @ConditionalOnProperty

If the condition is based on one property value, @ConditionalOnProperty is usually enough.

1import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
2import org.springframework.context.annotation.Bean;
3import org.springframework.context.annotation.Configuration;
4
5@Configuration
6public class ClientConfiguration {
7
8    @Bean
9    @ConditionalOnProperty(prefix = "feature.mail", name = "enabled", havingValue = "true")
10    public MailClient mailClient() {
11        return new MailClient();
12    }
13}

And the properties file:

feature.mail.enabled=true

This is the standard Spring Boot approach. Even if you also bind feature.mail.* into a configuration properties class, the condition itself can rely directly on the property key.

Using @ConfigurationProperties Alongside the Condition

You can still bind the values into a typed object for the rest of the application.

1import org.springframework.boot.context.properties.ConfigurationProperties;
2
3@ConfigurationProperties(prefix = "feature.mail")
4public class MailProperties {
5    private boolean enabled;
6    private String host;
7
8    public boolean isEnabled() {
9        return enabled;
10    }
11
12    public void setEnabled(boolean enabled) {
13        this.enabled = enabled;
14    }
15
16    public String getHost() {
17        return host;
18    }
19
20    public void setHost(String host) {
21        this.host = host;
22    }
23}

Then use it in the bean method:

1import org.springframework.boot.context.properties.EnableConfigurationProperties;
2import org.springframework.context.annotation.Bean;
3import org.springframework.context.annotation.Configuration;
4
5@Configuration
6@EnableConfigurationProperties(MailProperties.class)
7public class ClientConfiguration {
8
9    @Bean
10    @ConditionalOnProperty(prefix = "feature.mail", name = "enabled", havingValue = "true")
11    public MailClient mailClient(MailProperties properties) {
12        return new MailClient(properties.getHost());
13    }
14}

This is usually cleaner than trying to make the condition depend on the already-bound object.

Why Not Condition Directly on the Properties Bean?

A common point of confusion is that @ConditionalOnProperty reads the environment, not the fully constructed @ConfigurationProperties bean. That is intentional. Conditions are evaluated while the context is deciding what bean definitions to register.

Because of that lifecycle, asking Spring to create bean A only if a bound properties bean has a certain runtime value is often the wrong level of abstraction. The environment property itself is the input that should drive the condition.

When You Need More Complex Logic

If the condition is more complicated than one property comparison, write a custom Condition.

1import org.springframework.context.annotation.Condition;
2import org.springframework.context.annotation.ConditionContext;
3import org.springframework.core.type.AnnotatedTypeMetadata;
4
5public class MailFeatureCondition implements Condition {
6    @Override
7    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
8        String enabled = context.getEnvironment().getProperty("feature.mail.enabled");
9        String host = context.getEnvironment().getProperty("feature.mail.host");
10        return "true".equalsIgnoreCase(enabled) && host != null && !host.isBlank();
11    }
12}

Use it like this:

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Conditional;
3import org.springframework.context.annotation.Configuration;
4
5@Configuration
6public class ClientConfiguration {
7
8    @Bean
9    @Conditional(MailFeatureCondition.class)
10    public MailClient mailClient() {
11        return new MailClient();
12    }
13}

This gives you full control when @ConditionalOnProperty is too limited.

Alternative: Always Create One Bean and Make It a No-Op

Sometimes conditional bean registration is overkill. If the bean is lightweight, it can be simpler to always register it and let the implementation disable itself based on the properties.

That can reduce configuration complexity, especially when many downstream beans depend on the type. The right choice depends on whether the feature flag changes object graph shape or only behavior.

Common Pitfalls

A common mistake is expecting Spring to evaluate a condition after @ConfigurationProperties binding has already happened. Bean conditions are usually based on environment state, not on fully initialized beans.

Another issue is forcing complex logic into @ConditionalOnProperty when a custom Condition would be clearer.

Developers also sometimes forget havingValue compares strings from the environment. That matters when the property is missing or has unexpected formatting.

Finally, keep the property key stable. Conditional bean registration is much easier to reason about when one well-named property controls the feature explicitly.

Summary

• Use @ConditionalOnProperty for simple property-based bean activation.
• Bind the same values into @ConfigurationProperties for typed access elsewhere.
• Do not expect the condition to depend on an already-created properties bean.
• Use a custom Condition when the activation rule is more complex.
• Sometimes a no-op implementation is simpler than conditional bean registration.