UI Components

The UI component library has components to build web front-ends.

Install

Add this to your gramex.yaml. Now, the UI component library is available at /ui/.

import:
  ui:
    path: $GRAMEXAPPS/ui/gramex.yaml
    YAMLURL: $YAMLURL/ui/

Change the $YAMLURL/ui/ to any path you want to expose the UI components at.

Themes

The UI component library ships with pre-defined Bootstrap themes from Bootswatch and Bootstrap Themes Guide.

Explore theme gallery

You can import them in your style.scss. For example:

// Include any one of these lines in your .scss file
@import "theme/bootstrap5"; // Bootstrap 5 default theme
@import "theme/default"; // Bootstrap 4 default theme
@import "theme/bootswatch/slate"; // Bootstrap 4 theme
@import "theme/themes-guide/fesca"; // Bootstrap 4 theme

Or you can link to these directly. For example:

<!-- Include any one of these links in your .scss file -->
<link rel="stylesheet" href="ui/theme/bootstrap5.scss" />
<link rel="stylesheet" href="ui/theme/default.scss" />
<link rel="stylesheet" href="ui/theme/bootswatch/slate.scss" />
<link rel="stylesheet" href="ui/theme/themes-guide/fresca.scss" />

Custom themes

You can customize themes by adding Bootstrap variables to the URL. For example:

<link
  rel="stylesheet"
  href="ui/theme/default.scss?primary=maroon&body-bg=lavender"
/>

Try the custom theme

You can also customize themes by adding these to your style.scss file. For example:

$primary: maroon;
$body-bg: lavender;
@import "theme/default.scss";

See the full list of Bootstrap variables.

Customize with a theme builder

Theme colors

You can add custom colors to the $theme-colors map in your style.scss file. For example:

$theme-colors: (
    "accent1": coral,
    "accent2": #3cb371,
  )
  @import "theme/default.scss";

You can now use .bg-accent1, .text-accent1, .btn-accent1, .border-accent1, etc., and similarly for accent2.

Libraries

UI Libraries are deprecated since Gramex 1.84. Use jsDelivr instead.

The Gramex UI component library ships commonly used UI libraries. These are accessible via /ui/package@version/file.js. For example, /ui/d3@7/dist/d3.min.js.

Prior to Gramex 1.84, these libraries were npm installed on Gramex. After Gramex 1.84, these URLs redirect to cdn.jsdelivr.net.

For example, /ui/d3@7/dist/d3.min.js redirects to https://cdn.jsdelivr.net/npm/ui/d3@7/dist/d3.min.js.

Explore UI libraries on CDN

Typography

Text sizes

Bootstrap provides the following absolute font-size classes:

Gramex UI components adds the following relative font-size classes that make a font smaller:

Text alignment

.text-middle aligns text vertically to middle

Normal text is aligned to the top

Letter spacing

Line height

Text opacity

Effects

Borders

.border-2 sets border-width: 2px.

Normal border
.border .border-2

.border-top, .border-right, .border-bottom and .border-left set the respective border-width to 1px.

.border-top
.border-right
.border-bottom
.border-left

.border-top-0, .border-right-0, .border-bottom-0 and .border-left-0 set the respective border-width to 0px.

.border-top-0
.border-right-0
.border-bottom-0
.border-left-0

Shadow

.shadow adds a shadow to a block element. For example:

.text-shadow adds a text shadow to inline text. For example:

Line without shadow
Line with text shadow

Backgrounds

Take this sample background image:

.bg-no-repeat sets background-repeat: no-repeat, which creates only one copy of the background image.

.bg-center centers the background image.

Background positioning utilities determine the overall positioning. .bg-tl stands for background-top-left. You can use bg-(top/center/bottom)-(left/center/right). USe with bg-no-repeat as follows:

.bg-tl
.bg-tc
.bg-tr
.bg-cl
.bg-cc
.bg-cr
.bg-bl
.bg-bc
.bg-br

.bg-space sets background-repeat: space, which distributes space evenly between background image copies.

.bg-round sets background-repeat: round, which ensures that the background image is not cut off (but may shrink).

.bg-cover sets background-size: cover. The background image will completely fill the element.

.bg-contain sets background-size: contain. The background image will completely fit in the element.

.bg-fixed sets background-size: fixed. The background will scroll with the page.

.bg-parellax sets background-size: parellax. The background will scroll with the page. This is the same as .bg-center .bg-no-repeat .bg-fixed and .bg-cover.

Gradient

.gradient-* classes darken colors in a specified direction.

.gradient-tl stands for gradient-top-left. You can use gradient-(top/center/bottom)-(left/center/right). Here’s an example combining the gradients with different .bg- classes:

.gradient-tl
.gradient-tc
.gradient-tr
.gradient-cl
.gradient-cc
.gradient-cr
.gradient-bl
.gradient-bc
.gradient-br

.gradient-light makes it a lightening gradient. Here’s an example combining the gradients with different .bg- classes:

.gradient-light .gradient-tl
.gradient-light .gradient-tc
.gradient-light .gradient-tr
.gradient-light .gradient-cl
.gradient-light .gradient-cc
.gradient-light .gradient-cr
.gradient-light .gradient-bl
.gradient-light .gradient-bc
.gradient-light .gradient-br

Round corners

Add class="round" to add full rounded corners to any shape. For example:

.btn.btn-primary .round.btn.btn-primary

Add class="border-radius-{size} to control the size of the rounded corners.

.border-radius-xl .border-radius-lg .border-radius .border-radius-sm .no-border-radius

Ripple

.ripple adds a ripple effect to elements when clicked. Click to test:

Color states

These utility classes override the color of any element on :hover, :focus and :active – typically buttons and links. The classes are defined for each theme color.

Hover color classes set the color when you hover over an element. Hover to test:

Focus color classes set the color when you focus on an element. Click to test:

Active color classes set the color when you’re clicking on an element. Click to test:

Cursor styles

Layouts

Overlay

.overlay-black and .overlay-white overlays a dark or light layer on top of a relatively positioned element.

.overlay-black
.overlay-white

Position

.pos-* classes set the absolute position of elements.

.pos-tl stands for position: top-left. It sets top: 0 and left: 0. You can use pos-(top/center/bottom)-(left/center/right). Here’s an example of all .pos- classes inside a .position-relative block:

.pos-tl
.pos-tc
.pos-tr
.pos-cl
.pos-cc
.pos-cr
.pos-bl
.pos-bc
.pos-br
.pos-c
.pos-t
.pos-r
.pos-b
.pos-l

Height

.h-full sets min-height: 100vh. To ensure that a page background occupies full height of the screen, use:

<body class="h-full"></body>

Z-Index

.z-9 sets z-index: 9000. Use it to place an element on top of others

Components

Arrow

.arrow-<theme-color> creates an arrow shape. Add .h1, … .h6 or .display-1 .. .display-4 to control the height.

.arrow-primary.h5
.arrow-danger.h6

Add .arrow-tail to add a tail.

.arrow-primary.h5
.arrow-danger.h6

Divider

.divider adds a divider. For example, <div class="divider"></div> creates this divider:

Add .border-primary, etc to change the divider color. For example:

<div class="divider border-primary"></div>

creates this divider:

You can add any text inside the divider. For example:

<div class="divider">Text</div>
<div class="divider border-dark">
  <i class="fab fa-2x fa-twitter me-2"></i> Icons
</div>
<div class="divider border-primary">
  <div class="btn btn-primary round">Buttons</div>
</div>
Text
Icons
Buttons

Tail

.tail-* adds a tail to a container. .tail-tl adds a tail on the top side left position. You can use tail-{side}-{position}. For example:

.tail-lb.bg-primary
.tail-br.bg-success
.tail-tr.bg-warning

You can combine tails with .border, .round, .shadow and other styles. For example:

.tail-tc.border.border-primary.round.shadow

Deprecated

The following classes are deprecated: