Skip to content

Reference

Styles and components for enhancing the look of Streamlit apps at UNDP.

apply_style(title='UNDP')

Apply the styling based on UNDP Design System, including CSS rules and favicon.

Parameters:

Name Type Description Default
title str

The page title, shown in the browser tab.

 "UNDP"

Returns:

Type Description
None
Source code in st_undp/__init__.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
def apply_style(title: str = "UNDP") -> None:
    """
    Apply the styling based on UNDP Design System, including
    CSS rules and favicon.


    Parameters
    ----------
    title : str, default="UNDP"
        The page title, shown in the browser tab.

    Returns
    -------
    None
    """
    image = read_file("images/favicon.ico", "rb")
    st.set_page_config(
        page_title=title,
        page_icon=BytesIO(image),
        layout="wide",
        initial_sidebar_state="auto",
    )
    css = read_file("main.scss")
    body = f"<style>{css}</style>"
    st.html(body)

author(src, name, title, href)

Author component.

Parameters:

Name Type Description Default
src str

Image src attribute that can be a local path or URL to an image.

 required
name str

Name of the author.

 required
title str

Title of the author, typically a position.

 required
href str

URL the component points to when clicked.

 required

Returns:

Type Description
None
Source code in st_undp/components.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def author(src: str, name: str, title: str, href: str) -> None:
    """
    [Author](https://design.undp.org/?path=/docs/components-ui-components-authors-author--docs) component.

    Parameters
    ----------
    src : str
        Image `src` attribute that can be a local path or URL to an image.
    name : str
        Name of the author.
    title : str
        Title of the author, typically a position.
    href : str
        URL the component points to when clicked.

    Returns
    -------
    None
    """
    kwargs = locals()
    template = env.get_template("author.html")
    body = template.render(**kwargs)
    st.html(body)

author_card(src, name, title, summary, href, link='view', width=4)

Author card component.

Parameters:

Name Type Description Default
src str

Image src attribute that can be a local path or URL to an image.

 required
name str

Name of the author.

 required
title str

Title of the author, typically a position.

 required
summary str

Summary text displayed below the author.

 required
href str

URL the component points to when clicked.

 required
link str

Text displayed below the summary, typically "READ MORE" or similar.

 'view'
width int

Component width using a 12-grid scheme.

 4

Returns:

Type Description
None
Source code in st_undp/components.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
def author_card(
    src: str,
    name: str,
    title: str,
    summary: str,
    href: str,
    link: str = "view",
    width: int = 4,
) -> None:
    """
    [Author card](https://design.undp.org/?path=/docs/components-ui-components-authors-author-card--docs) component.

    Parameters
    ----------
    src : str
        Image `src` attribute that can be a local path or URL to an image.
    name : str
        Name of the author.
    title : str
        Title of the author, typically a position.
    summary : str
        Summary text displayed below the author.
    href : str
        URL the component points to when clicked.
    link : str
        Text displayed below the summary, typically "READ MORE" or similar.
    width : int, default=4
        Component width using a 12-grid scheme.

    Returns
    -------
    None
    """
    kwargs = locals()
    template = env.get_template("author-card.html")
    body = template.render(**kwargs)
    st.html(body)

author_summary(src, name, title, summary)

Author summary component.

Parameters:

Name Type Description Default
src str

Image src attribute that can be a local path or URL to an image.

 required
name str

Name of the author.

 required
title str

Title of the author, typically a position.

 required
summary str

Summary text displayed below the author.

 required

Returns:

Type Description
None
Source code in st_undp/components.py 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def author_summary(src: str, name: str, title: str, summary: str) -> None:
    """
    [Author summary](https://design.undp.org/?path=/docs/components-ui-components-author-summary--docs) component.
    Parameters
    ----------
    src : str
        Image `src` attribute that can be a local path or URL to an image.
    name : str
        Name of the author.
    title : str
        Title of the author, typically a position.
    summary : str
        Summary text displayed below the author.

    Returns
    -------
    None
    """
    template = env.get_template("author-summary.html")
    body = template.render(src=src, name=name, title=title, summary=summary)
    st.html(body)

breadcrumb(items)

Breadcrumbs component.

The breadcrumbs are arranged in the same order as dictionary keys. Last item's value is ignored and can be set to None.

Parameters:

Name Type Description Default
items dict[str, str]

Mapping from names to URLs.

 required

Returns:

Type Description
None
Source code in st_undp/components.py 
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
def breadcrumb(items: dict[str, str]) -> None:
    """
    [Breadcrumbs](https://design.undp.org/?path=/docs/components-navigation-components-breadcrumbs--docs) component.

    The breadcrumbs are arranged in the same order as dictionary keys. Last item's value is ignored and can be
    set to None.

    Parameters
    ----------
    items : dict[str, str]
        Mapping from names to URLs.

    Returns
    -------
    None
    """
    template = env.get_template("breadcrumb.html")
    body = template.render(items=items)
    st.html(body)

content_card(src, caption, href, tag='news', width=12)

Content card component (with image).

Parameters:

Name Type Description Default
src str

Image src attribute that can be a local path or URL to an image.

 required
caption str

Caption text displayed below the image.

 required
href str

URL the component points to when clicked.

 required
tag str

Tag text shown above the image.

 "news"
width int

Component width using a 12-grid scheme.

 12

Returns:

Type Description
None
Source code in st_undp/components.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
def content_card(
    src: str, caption: str, href: str, tag: str = "news", width: int = 12
) -> None:
    """
    [Content card](https://design.undp.org/?path=/docs/components-ui-components-cards-content-card-with-image--docs) component
    (with image).

    Parameters
    ----------
    src : str
        Image `src` attribute that can be a local path or URL to an image.
    caption : str
        Caption text displayed below the image.
    href : str
        URL the component points to when clicked.
    tag : str, default="news"
        Tag text shown above the image.
    width : int, default=12
        Component width using a 12-grid scheme.

    Returns
    -------
    None
    """
    kwargs = locals()
    template = env.get_template("content-card.html")
    body = template.render(**kwargs)
    st.html(body)

download_card(src, title, format, href, variant='default')

Download card component.

Parameters:

Name Type Description Default
src str | None

Image src attribute that can be a local path or URL to an image.

 required
title str

Title of the document displayed on the card.

 required
format str

Format of the file displayed on the card, including file size, e.g., "PDF (800kb)".

 required
href str

URL the component points to when clicked, typically a download link.

 required
variant Literal['publication', 'card', 'default']

One of the three card variants. If "default", src should be set to None.

 "default"

Returns:

Type Description
None
Source code in st_undp/components.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
def download_card(
    src: str | None,
    title: str,
    format: str,
    href: str,
    variant: Literal["publication", "card", "default"] = "default",
) -> None:
    """
    [Download card](https://design.undp.org/?path=/docs/components-ui-components-cards-download-card--docs) component.

    Parameters
    ----------
    src : str | None
        Image `src` attribute that can be a local path or URL to an image.
    title : str
        Title of the document displayed on the card.
    format : str
        Format of the file displayed on the card, including file size, e.g., "PDF (800kb)".
    href : str
        URL the component points to when clicked, typically a download link.
    variant : Literal["publication", "card", "default"], default="default"
        One of the three card variants. If "default", `src` should be set to `None`.

    Returns
    -------
    None
    """
    if variant != "default":
        template = env.get_template("download-card-image.html")
        image = template.render(src=src, variant=variant)
    else:
        image = ""
    template = env.get_template("download-card.html")
    body = template.render(title=title, format=format, image=image, href=href)
    st.html(body)

featured_card(src, title, summary, href, tag='news', width=12)

Featured card component.

Parameters:

Name Type Description Default
src str

Image src attribute that can be a local path or URL to an image.

 required
title str

Title displayed on the card in bold.

 required
summary str

Summary text displayed below the title.

 required
href str

URL the component points to when clicked.

 required
tag str

Tag text shown above the title.

 "news"
width int

Component width using a 12-grid scheme.

 12

Returns:

Type Description
None
Source code in st_undp/components.py 
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
def featured_card(
    src: str,
    title: str,
    summary: str,
    href: str,
    tag: str = "news",
    width: int = 12,
) -> None:
    """
    [Featured card](https://design.undp.org/?path=/docs/components-ui-components-cards-featured-card--docs) component.

    Parameters
    ----------
    src : str
        Image `src` attribute that can be a local path or URL to an image.
    title : str
        Title displayed on the card in bold.
    summary : str
        Summary text displayed below the title.
    href : str
        URL the component points to when clicked.
    tag : str, default="news"
        Tag text shown above the title.
    width : int, default=12
        Component width using a 12-grid scheme.

    Returns
    -------
    None
    """
    kwargs = locals()
    template = env.get_template("featured-card.html")
    body = template.render(**kwargs)
    st.html(body)

footer(columns='default')

Footer component.

Parameters:

Name Type Description Default
columns Literal['dfx', 'default'] | dict[str, dict[str, str]]

Either a literal specifying the type of the footer to use or a mapping from column titles to column items.

 "default"

Returns:

Type Description
None
Source code in st_undp/components.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def footer(
    columns: Literal["dfx", "default"] | dict[str, dict[str, str]] = "default"
) -> None:
    """
    [Footer](https://design.undp.org/?path=/docs/components-ui-components-footer--docs) component.

    Parameters
    ----------
    columns : Literal["dfx", "default"] | dict[str, dict[str, str]], default="default"
        Either a literal specifying the type of the footer to use or a mapping from column titles to column items.

    Returns
    -------
    None
    """
    if isinstance(columns, str):
        data = read_file(f"data/footer-{columns}.json")
        columns = json.loads(data)
    elif isinstance(columns, dict):
        pass
    else:
        raise ValueError("Columns must one of 'dfx', 'default', or a mapping.")
    items = []
    for title, pages in columns.items():
        item = __footer_item(title=title, pages=pages)
        items.append(item)
    template = env.get_template("footer.html")
    body = template.render(items=items)
    st.html(body)

header(title, subtitle, title_href=None, subtitle_href=None, pages=None, logo='undp')

Header component.

Parameters:

Name Type Description Default
title str

Title displayed in the header.

 required
subtitle str

Subtitle displayed in the header below the title.

 required
title_href str | None

URL assigned to the title.

 None
subtitle_href str | None

URL assigned to the subtitle.

 None
pages list[Page] | None

List of pages to add as navigation in the header.

 None
logo Literal['undp', 'pnud']

One of the two versions of the logo to use.

 "undp"

Returns:

Type Description
None
Source code in st_undp/components.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def header(
    title: str,
    subtitle: str,
    title_href: str | None = None,
    subtitle_href: str | None = None,
    pages: list[st.Page] | None = None,
    logo: Literal["undp", "pnud"] = "undp",
) -> None:
    """
    [Header](https://design.undp.org/?path=/docs/components-navigation-components-main-navigation-country-header--docs) component.

    Parameters
    ----------
    title : str
        Title displayed in the header.
    subtitle : str
        Subtitle displayed in the header below the title.
    title_href : str | None, optional
        URL assigned to the title.
    subtitle_href : str | None, optional
        URL assigned to the subtitle.
    pages : list[st.Page] | None, optional
        List of pages to add as navigation in the header.
    logo : Literal["undp", "pnud"], default="undp"
        One of the two versions of the logo to use.

    Returns
    -------
    None
    """
    kwargs = locals()
    # read the logo image
    image = read_file(f"images/{logo}-logo-blue.svg", "r")
    data = b64encode(image.encode("utf-8")).decode("utf-8")

    # update the variable as needed
    if kwargs["pages"]:
        kwargs["pages"] = {page.title: page.url_path for page in kwargs["pages"]}
    else:
        kwargs["pages"] = {}
    kwargs["logo"] = f"data:image/svg+xml;base64,{data}"

    template = env.get_template("header.html")
    body = template.render(**kwargs)
    st.html(body)

image_card(src, summary, href, width=12)

Image reveal card component.

Parameters:

Name Type Description Default
src str

Image src attribute that can be a local path or URL to an image.

 required
summary str

Summary text displayed below the image.

 required
href str

URL the component points to when clicked.

 required
width int

Component width using a 12-grid scheme.

 12

Returns:

Type Description
None
Source code in st_undp/components.py 
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
def image_card(src: str, summary: str, href: str, width: int = 12) -> None:
    """
    [Image reveal card](https://design.undp.org/?path=/docs/components-ui-components-cards-image-reveal-card--docs) component.

    Parameters
    ----------
    src : str
        Image `src` attribute that can be a local path or URL to an image.
    summary : str
        Summary text displayed below the image.
    href : str
        URL the component points to when clicked.
    width : int, default=12
        Component width using a 12-grid scheme.

    Returns
    -------
    None
    """
    kwargs = locals()
    template = env.get_template("image-card.html")
    body = template.render(**kwargs)
    st.html(body)

stats_card(value, title, text='')

Stats card component.

Parameters:

Name Type Description Default
value int | float | str

Value to be displayed, typically a number, percent etc.

 required
title str

Title to be displayed below the number.

 required
text str

Additional smaller text to be displayed below the title.

 ''

Returns:

Type Description
None
Source code in st_undp/components.py 
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
def stats_card(value: int | float | str, title: str, text: str = "") -> None:
    """
    [Stats card](https://design.undp.org/?path=/docs/components-ui-components-cards-stats-card--docs) component.

    Parameters
    ----------
    value : int | float | str
        Value to be displayed, typically a number, percent etc.
    title : str
        Title to be displayed below the number.
    text : str
        Additional smaller text to be displayed below the title.

    Returns
    -------
    None
    """
    body = f"""
        <div class='stat-card-smaller'>
            <h3>{value}</h3>
            <h4>{title}</h4>
            <p>{text}</p>
        </div>
    """
    st.html(body)