# NiceGUI

[Button: icon:menu]

[](/)

[Installation](/#installation)

[Features](/#features)

[Demos](/#demos)

[Documentation](/documentation)

[Examples](/examples)

[Why?](/#why)

[Button]

[Button]

[](https://github.com/zauberzeug/nicegui/)

[Button: icon:more_vert]

# ElementFilter

## ElementFilter

Sometimes it is handy to search the Python element tree of the current page.
``ElementFilter()`` allows powerful filtering by kind of elements, markers and content.
It also provides a fluent interface to apply more filters like excluding elements or filtering for elements within a specific parent.
The filter can be used as an iterator to iterate over the found elements and is always applied while iterating and not when being instantiated.

And element is yielded if it matches all of the following conditions:

- The element is of the specified kind (if specified).
- The element is none of the excluded kinds.
- The element has all of the specified markers.
- The element has none of the excluded markers.
- The element contains all of the specified content.
- The element contains none of the excluded content.

- Its ancestors include all of the specified instances defined via ``within``.
- Its ancestors include none of the specified instances defined via ``not_within``.
- Its ancestors include all of the specified kinds defined via ``within``.
- Its ancestors include none of the specified kinds defined via ``not_within``.
- Its ancestors include all of the specified markers defined via ``within``.
- Its ancestors include none of the specified markers defined via ``not_within``.

Element "content" includes its text, label, icon, placeholder, value, message, content, source.
Partial matches like "Hello" in "Hello World!" are sufficient for content filtering.

:kind: filter by element type; the iterator will be of type ``kind``
:marker: filter by element markers; can be a list of strings or a single string where markers are separated by whitespace
:content: filter for elements which contain ``content`` in one of their content attributes like ``.text``, ``.value``, ``.source``, ...; can be a single string or a list of strings which all must match
:local_scope: if ``True``, only elements within the current scope are returned; by default the whole page is searched (this default behavior can be changed with ``ElementFilter.DEFAULT_LOCAL_SCOPE = True``)
:only_visible: if ``True``, filter out elements that are not visible or whose ancestors are not visible

main.py

[Button]

````python
from nicegui import ElementFilter, ui

with ui.card():
    ui.button('button A')
    ui.label('label A')

with ui.card().mark('important'):
    ui.button('button B')
    ui.label('label B')

ElementFilter(kind=ui.label).within(marker='important').classes('text-xl')

ui.run()
````

## Find all elements with text property

The `text` property is provided by a mixin called `TextElement`.
If we filter by such a mixin, the ElementFilter itself will provide a typed iterable.

main.py

[Button]

````python
from nicegui import ElementFilter, ui
from nicegui.elements.mixins.text_element import TextElement

with ui.card():
    ui.button('button')
    ui.icon('home')
    ui.label('label A')
    ui.label('label B')
    ui.html('HTML', sanitize=False)

ui.label(', '.join(b.text for b in ElementFilter(kind=TextElement)))

ui.run()
````

## Markers

Markers are a simple way to tag elements with a string which can be queried by an `ElementFilter`.

main.py

[Button]

````python
from nicegui import ElementFilter, ui

with ui.card().mark('red'):
    ui.label('label A')
with ui.card().mark('strong'):
    ui.label('label B')
with ui.card().mark('red strong'):
    ui.label('label C')

ElementFilter(marker='red').classes('bg-red-200')
ElementFilter(marker='strong').classes('text-bold')
ElementFilter(marker='red strong').classes('bg-red-600 text-white')

ui.run()
````

## Find elements on other pages

You can use the `app.clients` iterator to apply the element filter to all clients of a specific page.

main.py

[Button]

````python
import time
from nicegui import app, ui

@ui.page('/log')
def log_page():
    ui.log()

def log_time():
    for client in app.clients('/log'):
        with client:
            for log in ElementFilter(kind=ui.log):
                log.push(f'{time.strftime("%H:%M:%S")}')

@ui.page('/')
def page():
    ui.button('Log current time', on_click=log_time)
    ui.link('Open log', '/log', new_tab=True)

ui.run()
````

## Reference

## Initializer

:kind: filter by element type; the iterator will be of type ``kind``
:marker: filter by element markers; can be a list of strings or a single string where markers are separated by whitespace
:content: filter for elements which contain ``content`` in one of their content attributes like ``.text``, ``.value``, ``.source``, ...; can be a single string or a list of strings which all must match
:local_scope: if ``True``, only elements within the current scope are returned; by default the whole page is searched (this default behavior can be changed with ``ElementFilter.DEFAULT_LOCAL_SCOPE = True``)
:only_visible: if ``True``, filter out elements that are not visible or whose ancestors are not visible

## Methods

**`classes`**`(add: str | None = None, remove: str | None = None, replace: str | None = None) -> Self`

Apply, remove, or replace HTML classes.

This allows modifying the look of the element or its layout using `Tailwind <https://tailwindcss.com/>`_ or `Quasar <https://quasar.dev/>`_ classes.

Removing or replacing classes can be helpful if predefined classes are not desired.

:param add: whitespace-delimited string of classes
:param remove: whitespace-delimited string of classes to remove from the element
:param replace: whitespace-delimited string of classes to use instead of existing ones

**`exclude`**`(kind: type[Element] | None = None, marker: str | None = None, content: str | None = None) -> Self`

Exclude elements with specific element type, marker or content.

**`not_within`**`(kind: type[Element] | None = None, marker: str | None = None, instance: Element | list[Element] | None = None) -> Self`

Exclude elements which have a parent of a specific type or marker.

**`props`**`(add: str | None = None, remove: str | None = None) -> Self`

Add or remove props.

This allows modifying the look of the element or its layout using `Quasar <https://quasar.dev/>`_ props.
Since props are simply applied as HTML attributes, they can be used with any HTML element.

Boolean properties are assumed ``True`` if no value is specified.

:param add: whitespace-delimited list of either boolean values or key=value pair to add
:param remove: whitespace-delimited list of property keys to remove

**`style`**`(add: str | None = None, remove: str | None = None, replace: str | None = None) -> Self`

Apply, remove, or replace CSS definitions.

Removing or replacing styles can be helpful if the predefined style is not desired.

:param add: semicolon-separated list of styles to add to the element
:param remove: semicolon-separated list of styles to remove from the element
:param replace: semicolon-separated list of styles to use instead of existing ones

**`within`**`(kind: type[Element] | None = None, marker: str | None = None, instance: Element | list[Element] | None = None) -> Self`

Filter elements which have a specific match in the parent hierarchy.

**Nice**GUI

The Python UI framework that shows up in your browser.

[](https://github.com/zauberzeug/nicegui/)

[](https://discord.gg/TEpFeAaF4f)

[](https://www.reddit.com/r/nicegui/)

Resources

[Documentation](/documentation)

[Examples](/examples)

[LLM reference](/llms.txt)

[GitHub](https://github.com/zauberzeug/nicegui/)

[PyPI](https://pypi.org/project/nicegui/)

Community

[Discussions](https://github.com/zauberzeug/nicegui/discussions)

[Discord](https://discord.gg/TEpFeAaF4f)

[Reddit](https://www.reddit.com/r/nicegui/)

[Contributing](https://github.com/zauberzeug/nicegui/blob/main/CONTRIBUTING.md)

[Sponsors](https://github.com/sponsors/zauberzeug)

Legal

[Imprint](/imprint_privacy#imprint)

[Privacy](/imprint_privacy#privacy)

Made with NiceGUI by [Zauberzeug](https://zauberzeug.com)

© 2026 [Zauberzeug GmbH](https://zauberzeug.com)