Skip to main content

CircleAvatar

A circle that represents a user.

If foreground_image_src fails then background_image_src is used, and if this also fails, then bgcolor is used.

Example:

ft.CircleAvatar(
    content=ft.Text("AB"),
    bgcolor=ft.Colors.PRIMARY,
    color=ft.Colors.ON_PRIMARY,
)
CircleAvatar
Basic CircleAvatar

Inherits: LayoutControl

Properties

  • background_image_src - The source (local asset file or URL) of the background image in the circle.
  • bgcolor - The color with which to fill the circle.
  • color - The default color for text in this avatar.
  • content - The content of this avatar.
  • foreground_image_src - The source (local asset file or URL) of the foreground image in the circle.
  • max_radius - The maximum size of the avatar, expressed as the radius (half the diameter).
  • min_radius - The minimum size of the avatar, expressed as the radius (half the diameter).
  • radius - The size of the avatar, expressed as the radius (half the diameter).

Events

Examples​

Live example

User avatars​

import flet as ft


def main(page: ft.Page):
    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    # a "normal" avatar with background image
                    ft.CircleAvatar(
                        foreground_image_src="https://avatars.githubusercontent.com/u/5041459?s=88&v=4",
                        content=ft.Text("FF"),
                    ),
                    # avatar with failing foreground image and fallback text
                    ft.CircleAvatar(
                        foreground_image_src="https://avatars.githubusercontent.com/u/_5041459?s=88&v=4",
                        content=ft.Text("FF"),
                    ),
                    # avatar with icon, aka icon with inverse background
                    ft.CircleAvatar(content=ft.Icon(ft.Icons.ABC)),
                    # avatar with icon and custom colors
                    ft.CircleAvatar(
                        content=ft.Icon(ft.Icons.WARNING_ROUNDED),
                        color=ft.Colors.YELLOW_200,
                        bgcolor=ft.Colors.AMBER_700,
                    ),
                    # avatar with online status
                    ft.Stack(
                        width=40,
                        height=40,
                        controls=[
                            ft.CircleAvatar(
                                foreground_image_src="https://avatars.githubusercontent.com/u/5041459?s=88&v=4"
                            ),
                            ft.Container(
                                alignment=ft.Alignment.BOTTOM_LEFT,
                                content=ft.CircleAvatar(
                                    bgcolor=ft.Colors.GREEN, radius=5
                                ),
                            ),
                        ],
                    ),
                ]
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)
user-avatars

Properties​

background_image_srcclass-attributeinstance-attribute​

background_image_src: Optional[Union[str, bytes]] = None

The source (local asset file or URL) of the background image in the circle. Changing the background image will cause the avatar to animate to the new image.

If this avatar is to have the user's initials, use content instead.

Typically used as a fallback image for foreground_image_src.

bgcolorclass-attributeinstance-attribute​

bgcolor: Optional[ColorValue] = None

The color with which to fill the circle.

Changing the background color will cause this avatar to animate to the new color.

colorclass-attributeinstance-attribute​

color: Optional[ColorValue] = None

The default color for text in this avatar.

Defaults to the primary text theme color if no bgcolor is specified.

contentclass-attributeinstance-attribute​

content: Optional[StrOrControl] = None

The content of this avatar.

Typically a Text control.

Tip

If this avatar is to have an image, use background_image_src instead.

foreground_image_srcclass-attributeinstance-attribute​

foreground_image_src: Optional[Union[str, bytes]] = None

The source (local asset file or URL) of the foreground image in the circle.

Fallbacks to background_image_src.

Typically used as profile image.

max_radiusclass-attributeinstance-attribute​

max_radius: Annotated[Optional[Number], V.ge(0)] = None

The maximum size of the avatar, expressed as the radius (half the diameter). If set to a non None value, then radius must be None (default).

Defaults to float('inf') i.e. infinity.

Raises:

  • ValueError - If it is not greater than or equal to 0.0.
  • ValueError - If it is set while radius is set.

min_radiusclass-attributeinstance-attribute​

min_radius: Annotated[Optional[Number], V.ge(0)] = None

The minimum size of the avatar, expressed as the radius (half the diameter). If set to a non None value, then radius must be None (default).

Defaults to 0.0.

Raises:

  • ValueError - If it is not greater than or equal to 0.0.
  • ValueError - If it is set while radius is set.

radiusclass-attributeinstance-attribute​

radius: Annotated[Optional[Number], V.ge(0)] = None

The size of the avatar, expressed as the radius (half the diameter).

If set to a non None value, then neither min_radius nor max_radius may be specified.

Raises:

  • ValueError - If it is not greater than or equal to 0.
  • ValueError - If it is set while min_radius or max_radius is set.

Events​

on_image_errorclass-attributeinstance-attribute​

on_image_error: Optional[ControlEventHandler[CircleAvatar]] = None

Called when an error occurs while loading the background_image_src or foreground_image_src.

The data property of the event handler argument is a string whose value is either "background" or "foreground" indicating the error's origin.