Base-class for all selects. More...

#include <select.h>

Inheritance diagram for esphome::select::Select:

Public Member Functions
ESPDEPRECATED("Use current_option() instead of .state. Will be removed in 2026.7.0", "2026.1.0") std	Select ()=default

	~Select ()=default

void	publish_state (const std::string &state)

void	publish_state (const char *state)

void	publish_state (size_t index)

StringRef	current_option () const
	Return the currently selected option, or empty StringRef if no state.

SelectCall	make_call ()
	Instantiate a SelectCall object to modify this select component's state.

bool	has_option (const std::string &option) const
	Return whether this select component contains the provided option.

bool	has_option (const char *option) const

bool	has_index (size_t index) const
	Return whether this select component contains the provided index offset.

size_t	size () const
	Return the number of options in this select component.

optional< size_t >	index_of (const char *option, size_t len) const
	Find the (optional) index offset of the provided option value.

optional< size_t >	index_of (const std::string &option) const

optional< size_t >	index_of (const char *option) const

optional< size_t >	active_index () const
	Return the (optional) index offset of the currently active option.

optional< std::string >	at (size_t index) const
	Return the (optional) option value at the provided index offset.

const char *	option_at (size_t index) const
	Return the option value at the provided index offset (as const char* from flash).

void	add_on_state_callback (std::function< void(size_t)> &&callback)

Public Member Functions inherited from esphome::EntityBase
const StringRef &	get_name () const

bool	has_own_name () const

ESPDEPRECATED("object_id mangles names and all object_id methods are planned for removal " "(see https://github.com/esphome/backlog/issues/76). " "Now is the time to stop using object_id. If still needed, use get_object_id_to() " "which will remain available longer. get_object_id() will be removed in 2026.7.0", "2025.12.0") std uint32_t	get_object_id_hash ()

StringRef	get_object_id_to (std::span< char, OBJECT_ID_MAX_LEN > buf) const
	Get object_id with zero heap allocation For static case: returns StringRef to internal storage (buffer unused) For dynamic case: formats into buffer and returns StringRef to buffer.

size_t	write_object_id_to (char *buf, size_t buf_size) const
	Write object_id directly to buffer, returns length written (excluding null) Useful for building compound strings without intermediate buffer.

bool	is_internal () const

	ESPDEPRECATED ("set_internal() is undefined behavior at runtime — components and Home Assistant are NOT " "notified. Use the 'internal:' YAML key instead. Will be removed in 2027.3.0.", "2026.3.0") void set_internal(bool internal)

bool	is_disabled_by_default () const

EntityCategory	get_entity_category () const

const char *	get_device_class_to (std::span< char, MAX_DEVICE_CLASS_LENGTH > buffer) const

template<typename T = int>
StringRef	get_device_class_ref () const

template<typename T = int>
std::string	get_device_class () const

	ESPDEPRECATED ("Use get_device_class_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") StringRef get_device_class_ref() const

ESPDEPRECATED("Use get_device_class_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") std StringRef	get_unit_of_measurement_ref () const

ESPDEPRECATED("Use get_unit_of_measurement_ref() instead for better performance (avoids string copy). Will be " "removed in ESPHome 2026.9.0", "2026.3.0") std const char *	get_icon_to (std::span< char, MAX_ICON_LENGTH > buffer) const
	Get the unit of measurement as std::string (deprecated, prefer get_unit_of_measurement_ref())

template<typename T = int>
StringRef	get_icon_ref () const

template<typename T = int>
std::string	get_icon () const

	ESPDEPRECATED ("Use get_icon_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") StringRef get_icon_ref() const

ESPDEPRECATED("Use get_icon_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") std uint32_t	get_device_id () const

Device *	get_device () const

bool	has_state () const

void	set_has_state (bool state)

	ESPDEPRECATED ("Use make_entity_preference<T>() instead, or preferences won't be migrated. " "See https://github.com/esphome/backlog/issues/85. Will be removed in 2027.1.0.", "2026.7.0") uint32_t get_preference_hash()
	Get a unique hash for storing preferences/settings for this entity.

template<typename T >
ESPPreferenceObject	make_entity_preference (uint32_t version=0)
	Create a preference object for storing this entity's state/settings.

Data Fields
SelectTraits	traits

Protected Member Functions
virtual void	control (size_t index)
	Set the value of the select by index, this is an optional virtual method.

virtual void	control (const std::string &value)
	Set the value of the select, this is a virtual method that each select integration can implement.

Protected Member Functions inherited from esphome::EntityBase
friend	void::setup ()

friend	void::original_setup ()

void	configure_entity_ (const char *name, uint32_t object_id_hash, uint32_t entity_fields)
	Combined entity setup from codegen: set name, object_id hash, entity string indices, and flags.

void	set_device_ (Device *device)

ESPPreferenceObject	make_entity_preference_ (size_t size, uint32_t version)
	Non-template helper for make_entity_preference() to avoid code bloat.

void	calc_object_id_ ()

Protected Attributes
size_t	active_index_ {0}

LazyCallbackManager< void(size_t)>	state_callback_

Protected Attributes inherited from esphome::EntityBase
StringRef	name_

uint32_t	object_id_hash_ {}

Device *	device_ {}

struct esphome::EntityBase::EntityFlags	flags_

uint8_t	device_class_idx_ {}

uint8_t	uom_idx_ {}

uint8_t	icon_idx_ {}

Detailed Description

Base-class for all selects.

A select can use publish_state to send out a new value.

Definition at line 29 of file select.h.

Constructor & Destructor Documentation

◆ Select()

ESPDEPRECATED("Use current_option() instead of .state. Will be removed in 2026.7.0", "2026.1.0") std esphome::select::Select::Select ( )

default

◆ ~Select()

esphome::select::Select::~Select ( )

default

Member Function Documentation

◆ active_index()

optional< size_t > esphome::select::Select::active_index ( ) const

Return the (optional) index offset of the currently active option.

Definition at line 70 of file select.cpp.

◆ add_on_state_callback()

void esphome::select::Select::add_on_state_callback ( std::function< void(size_t)> && callback )

Definition at line 45 of file select.cpp.

◆ at()

optional< std::string > esphome::select::Select::at ( size_t index ) const

Return the (optional) option value at the provided index offset.

Definition at line 77 of file select.cpp.

◆ control() [1/2]

virtual void esphome::select::Select::control ( const std::string & value )

inlineprotectedvirtual

Set the value of the select, this is a virtual method that each select integration can implement.

IMPORTANT: At least ONE of the two control() methods must be overridden by derived classes. Overriding control(size_t) is PREFERRED as it avoids string conversions.

This method is called by control(size_t) when not overridden, or directly by external code. Default implementation converts to index and calls control(size_t).

Parameters

value The value as validated by the caller.

Definition at line 108 of file select.h.

◆ control() [2/2]

virtual void esphome::select::Select::control ( size_t index )

inlineprotectedvirtual

Set the value of the select by index, this is an optional virtual method.

IMPORTANT: At least ONE of the two control() methods must be overridden by derived classes. Overriding this index-based version is PREFERRED as it avoids string conversions.

This method is called by the SelectCall when the index is already known. Default implementation converts to string and calls control(const std::string&).

Parameters

index The index as validated by the SelectCall.

Reimplemented in esphome::copy::CopySelect, esphome::demo::DemoSelect, esphome::es8388::ADCInputMicSelect, esphome::es8388::DacOutputSelect, esphome::ld2410::BaudRateSelect, esphome::ld2410::DistanceResolutionSelect, esphome::ld2410::LightOutControlSelect, esphome::ld2412::BaudRateSelect, esphome::ld2412::DistanceResolutionSelect, esphome::ld2412::LightOutControlSelect, esphome::ld2420::LD2420Select, esphome::ld2450::BaudRateSelect, esphome::ld2450::ZoneTypeSelect, esphome::logger::LoggerLevelSelect, esphome::lvgl::LVGLSelect, esphome::modbus_controller::ModbusSelect, esphome::seeed_mr24hpc1::ExistenceBoundarySelect, esphome::seeed_mr24hpc1::MotionBoundarySelect, esphome::seeed_mr24hpc1::SceneModeSelect, esphome::seeed_mr24hpc1::UnmanTimeSelect, esphome::seeed_mr60fda2::HeightThresholdSelect, esphome::seeed_mr60fda2::InstallHeightSelect, esphome::seeed_mr60fda2::SensitivitySelect, esphome::template_::TemplateSelect< HAS_LAMBDA, OPTIMISTIC, RESTORE_VALUE, INITIAL_OPTION_INDEX >, esphome::template_::TemplateSelectWithSetAction< HAS_LAMBDA, OPTIMISTIC, RESTORE_VALUE, INITIAL_OPTION_INDEX >, and esphome::tuya::TuyaSelect.

Definition at line 96 of file select.h.

◆ current_option()

StringRef esphome::select::Select::current_option ( ) const

Return the currently selected option, or empty StringRef if no state.

The returned StringRef points to string literals from codegen (static storage). Traits are set once at startup and valid for the lifetime of the program.

Definition at line 41 of file select.cpp.

◆ has_index()

bool esphome::select::Select::has_index ( size_t index ) const

Return whether this select component contains the provided index offset.

Definition at line 53 of file select.cpp.

◆ has_option() [1/2]

bool esphome::select::Select::has_option ( const char * option ) const

Definition at line 51 of file select.cpp.

◆ has_option() [2/2]

bool esphome::select::Select::has_option ( const std::string & option ) const

Return whether this select component contains the provided option.

Definition at line 49 of file select.cpp.

◆ index_of() [1/3]

optional< size_t > esphome::select::Select::index_of ( const char * option ) const

inline

Definition at line 68 of file select.h.

◆ index_of() [2/3]

optional< size_t > esphome::select::Select::index_of	(	const char *	option,
		size_t	len ) const

Find the (optional) index offset of the provided option value.

Definition at line 60 of file select.cpp.

◆ index_of() [3/3]

optional< size_t > esphome::select::Select::index_of ( const std::string & option ) const

inline

Definition at line 67 of file select.h.

◆ make_call()

SelectCall esphome::select::Select::make_call ( )

inline

Instantiate a SelectCall object to modify this select component's state.

Definition at line 53 of file select.h.

◆ option_at()

const char * esphome::select::Select::option_at ( size_t index ) const

Return the option value at the provided index offset (as const char* from flash).

Definition at line 85 of file select.cpp.

◆ publish_state() [1/3]

void esphome::select::Select::publish_state ( const char * state )

Definition at line 13 of file select.cpp.

◆ publish_state() [2/3]

void esphome::select::Select::publish_state ( const std::string & state )

Definition at line 11 of file select.cpp.

◆ publish_state() [3/3]

void esphome::select::Select::publish_state ( size_t index )

Definition at line 22 of file select.cpp.

◆ size()

size_t esphome::select::Select::size ( ) const

Return the number of options in this select component.

Definition at line 55 of file select.cpp.

Field Documentation

◆ active_index_

size_t esphome::select::Select::active_index_ {0}

protected

Definition at line 84 of file select.h.

◆ state_callback_

LazyCallbackManager<void(size_t)> esphome::select::Select::state_callback_

protected

Definition at line 115 of file select.h.

◆ traits

SelectTraits esphome::select::Select::traits

Definition at line 31 of file select.h.

The documentation for this class was generated from the following files:

esphome/components/select/select.h
esphome/components/select/select.cpp

Public Member Functions

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Select()

◆ ~Select()

Member Function Documentation

◆ active_index()

◆ add_on_state_callback()

◆ at()

◆ control() [1/2]

◆ control() [2/2]

◆ current_option()

◆ has_index()

◆ has_option() [1/2]

◆ has_option() [2/2]

◆ index_of() [1/3]

◆ index_of() [2/3]

◆ index_of() [3/3]

◆ make_call()

◆ option_at()

◆ publish_state() [1/3]

◆ publish_state() [2/3]

◆ publish_state() [3/3]

◆ size()

Field Documentation

◆ active_index_

◆ state_callback_

◆ traits