express.ui.Theme

express.ui.Theme(self, preset='shiny', name=None, include_paths=None)

Create a custom Shiny theme.

The Theme class allows you to create a custom Shiny theme by providing custom Sass code. The theme can be based on one of the available presets, such as "shiny" or "bootstrap", or a Bootswatch theme. Use the .add_*() methods can be chained together to add custom Sass functions, defaults, mixins, and rules.

Pass the Theme object directly to the theme argument of any Shiny page function, such as page_sidebar or page_navbar. In Shiny Express apps, use the theme argument of page_opts to set the app theme.

Note: Compiling custom themes requires the libsass package, which is not installed by default with Shiny. Use pip install libsass or pip install "shiny[theme]" to install it.

Customized themes are compiled to CSS when the theme is used. The Theme class caches the compiled CSS so that it's only compiled for the first user to load your app, but you can speed up app loading (and avoid the runtime libsass dependency) by pre-compiling the theme CSS and saving it to a file. To do this, use the .to_css() method to render the theme to a single minified CSS string.

my_theme.py

from pathlib import Path

from shiny import ui

my_theme = (
    ui.Theme("shiny")
    .add_defaults(
        my_purple="#aa00aa",
    )
    .add_mixins(
        headings_color="$my-purple",
    )
)

with open(Path(__file__).parent / "my_theme.css", "w") as f:
    f.write(my_theme.to_css())

Run this script with python my_theme.py to generate the CSS file. Once saved to a file, the CSS can be used in any Shiny app by passing the file path to the theme argument instead of the Theme object.

app.py

from pathlib import Path

from shiny import App, ui

app_ui = ui.page_fluid(
    ui.h2("Hello, themed Shiny!"),
    # App content here
    title="My App",
    theme=Path(__file__).parent / "my_theme.css",
)

def server(input):
    pass

app = App(app_ui, server)

Parameters

preset: ShinyThemePreset = ‘shiny’

The name of the preset to use as a base. "shiny" is the default theme for Shiny apps and "bootstrap" uses standard Bootstrap 5 styling. Bootswatch theme presets are also available. Use Theme.available_presets() to see the full list.

name: Optional[str] = None

A custom name for the theme. If not provided, the preset name will be used.

include_paths: Optional[str | pathlib.Path | list[str | pathlib.Path]] = None

Additional paths to include when looking for Sass files used in @import statements in the theme. This can be a single path as a string or pathlib.Path, or a list of paths. The paths should point to directories containing additional Sass files that the theme depends on.

Raises

Type	Description
ValueError	If the preset is not a valid theme preset.

Methods

Name	Description
add_defaults	Add custom default values to the theme.
add_functions	Add custom Sass functions to the theme.
add_mixins	Add custom Sass mixins to the theme.
add_rules	Add custom Sass rules to the theme.
available_presets	Get a list of available theme presets.
to_css	Compile the theme to CSS and return the result as a string.
to_sass	Returns the custom theme as a single Sass string.

add_defaults

express.ui.Theme.add_defaults(*args, **kwargs)

Add custom default values to the theme.

Sass code added via this method will be placed before the default values of the theme preset, allowing you to override or extend the default values.

Parameters

*args: str = ()

Sass code, as a single or multiple strings, containing default value declarations to add.

**kwargs: str | float | int | bool | None = {}

Keyword arguments containing default value declarations to add. The keys should be Sass variable names using underscore casing that will be transformed automatically to kebab-case. For example, .add_defaults(primary_color="#ff0000") is equivalent to .add_defaults("$primary-color: #ff0000 !default;").

add_functions

express.ui.Theme.add_functions(*args)

Add custom Sass functions to the theme.

Sass code added via this method will be placed after the function declarations from the theme preset, allowing you to override or extend the default functions.

Parameters

*args: str = ()

The Sass functions to add as a single or multiple strings.

add_mixins

express.ui.Theme.add_mixins(*args, **kwargs)

Add custom Sass mixins to the theme.

Sass code added via this method will be placed after the mixin declarations from the theme preset, allowing you to override or extend the default mixins.

Parameters

*args: str = ()

Sass code, as a single or multiple strings, containing mixins to add.

**kwargs: str | float | int | bool | None = {}

Keyword arguments containing Sass value declarations to add. The keys should be Sass variable names using underscore casing that will be transformed automatically to kebab-case. For example, .add_mixins(primary_color="#ff0000") is equivalent to .add_mixins("$primary-color: #ff0000;").

add_rules

express.ui.Theme.add_rules(*args, **kwargs)

Add custom Sass rules to the theme.

Sass code added via this method will be placed after the rule declarations from the theme preset, allowing you to override or extend the default rules.

Parameters

*args: str = ()

Sass code, as a single or multiple strings, containing rules to add.

**kwargs: str | float | int | bool | None = {}

Keyword arguments containing Sass value declarations to add. The keys should be Sass variable names using underscore casing that will be transformed automatically to kebab-case. For example, .add_rules(primary_color="#ff0000") is equivalent to .add_rules("$primary-color: #ff0000;").

available_presets

express.ui.Theme.available_presets()

Get a list of available theme presets.

to_css

express.ui.Theme.to_css(compile_args=None)

Compile the theme to CSS and return the result as a string.

Parameters

compile_args: Optional[SassCompileArgs] = None

A dictionary of keyword arguments to pass to sass.compile().

Returns

Type	Description
str	The compiled CSS for the theme. The value is cached such that previously compiled themes are returned immediately. Adding additional custom Sass code or changing the preset will invalidate the cache.

to_sass

express.ui.Theme.to_sass()

Returns the custom theme as a single Sass string.

Returns

Type	Description
str	The custom theme as a single Sass string.