Although custom elements are globally accessible after initially imported, it is best practice to import elements when you need them.

import 'blackstone-ui/elements/btn'
let btn = document.createElement('b-btn')

// or
import Btn from 'blackstone-ui/elements/btn'
let btn = new Btn()

Align children elements in a grid

<b-grid cols="4">
    <b-paper dense colspan>Row 1</b-paper>
    <b-paper dense colspan="2">Row 2</b-paper>
    <b-paper dense>Row 3</b-paper>
    <b-paper dense>Row 4</b-paper>
</b-grid>

• gap - none, .5, 1, 2
• cols
  • 1-8
  • 2,1 or 1,2 (two-thirds/third)
  • 2,1,1 or 1,1,2 (half/quarter)
• align - start, center, end (defaults to stretch)

Effectively a "span" tag with attributes to apply styles

• xs, sm, lg, xl, xxl - size
• tone - critical, warning, info, muted
• muted - shorthand for tone="muted"
• bold, italic
• ucase, lcase, capitalize
• align - left, center, right, justify
• link - changes color on hover
• clip - keeps text on one line, clipping with ellipsis
• sup, sub - super/sub vertical align
• monospace
• block - change to a block element

Visually groups buttons together

<b-btn-group>
    <b-btn>Send</b-btn>
    <b-btn icon="down-open"></b-btn>
</b-btn-group>

Display an svg icon – See a full list of icons

<b-icon name="user"></b-icon>
<b-icon name="cog"></b-icon>

File icon has some default file formats defined, but you will inevitably want to add your own. To support this, you must deliberately call the "define" function before using the custom element.

import { css } from 'lit'
import defineFileIcon, {fileIconColors} from 'bui/elements/file-icon'

// list of predefined colors
// override them in this object or in the define method
console.log(fileIconColors)

// use default colors
defineFileIcon()

// use defaults with your own colors
defineFileIcon({
    // must be defined with lit-element css
    jpg: css`
        :host([ext="jpg"]),
        :host([ext="jpeg"]) {
            --color: orange;
        }
    `
})

<b-file-icon ext="pdf"></b-file-icon>
<b-file-icon ext="doc" style="--size:4em"></b-file-icon>

--b-file-icon-color-default - when no ext color
--b-file-icon-bgd-default - when no ext bgd
--b-file-icon-size
--b-file-icon-radius

A line divider

• short - makes the line short (not full width)
• vert - changes to a vertical line

deprecated, use <b-text sm muted></b-text> instead

A subdued (or sub text) text element that is slightly smaller and lighter in color

Simple element for displaying timestamps. If a string is given, it will be converted to a dayjs date. Or set the dayjs date using .date=${myDate}. dayjs.fromNow() will be rendered and updated every 1 minute.

<b-ts date="2020-04-23"></b-ts>
<b-ts .date=${myDate}></b-ts>

Default is an uppercase, bold, and slightly subdued (gray) text block for labeling. Can be altered to display as filled, outlined, or as a badge.

• xs - xtra small
• sm - small
• lg - large
• filled, filled="color"
• badge, badge="color"
• outline, outline="color"
• divider, divider="[center,right]"

• --dividerThickness

<b-ribbon>Ribbon</b-ribbon>
<b-ribbon pos="right">Ribbon</b-ribbon>

Note: make sure the correct parent element has a relative type position

• pos - left/right
• shadow - true/false
• value - can be used in place of inner html slot

• --width
• --height ex: set to 2em for 2 lines
• --padding top/bottom padding
• --color background color
• --shadow customize shadow attribute
• --offset defaults to slight offset to give depth

Create scalable avatars with initials or image with from a url or gravatar GUID

<b-avatar initials="KJ" size="40"></b-avatar>
<b-avatar initials="BT" size="40"></b-avatar>
<b-avatar initials="JD" size="40"></b-avatar>
<b-avatar initials="KJ" bgd="#E91E63" size="40"></b-avatar>
<b-avatar gravatar="6bd69795f929a40746cdf026a03b703e" size="40"></b-avatar>
<b-avatar url="https://i.imgur.com/6QKG2AG.png" size="40"></b-avatar>

• initials - will display a dash if not set
• bgd - defaults to selecting a color keyed from the initials
• color - text color, defaults to white
• size - default: 24
• gravatar - the GUID of a gravatar account
• url - specify a custom image to use

import {BgdColors} from 'avatar'
BgdColors = [/*...array of colors...*/]

Use to show a message when a view is empty. NOTE: make sure the parent element has position:relative (or absolute)

• xs - xtra small
• sm - small
• md - medium
• lg - large
• static - removes absolute pos and 100% height
• must-be="first" or "last" - will not display if not

An animated circle spinner to represent progress

• --size

Shows an overlay over the parent element with a b-spinner and optional label

Note: if the spinner is at the top level of a shadowroot, it will link itself to the host element as host.spinner

• show
• label
• lg - make spinner large
• dark

• --spinnerBgd
• --spinnerColor
• --spinnerSize

Display an audio control bar for playing audio. Provides seeking keyboard shortcuts when hovered over the element

<b-audio src="http://media.w3.org/2010/07/bunny/04-Death_Becomes_Fur.mp4"><b-audio>

// or via JS
import AudioPlayer from 'elements/audio'
let player = new AudioPlayer('http://media.w3.org/2010/07/bunny/04-Death_Becomes_Fur.mp4', {autoplay: true})

• src
• autoplay

TODO: provide better theming control

A slider/carousel element that will show one of the nested elements at time. A set of dots will be shown to represent the number of slides available.

Currently a very simple implementation with no animation or sliding. Maybe later we'll introduce animation and more features, like nav arrows

• --dotSize
• --dotPadding
• --dotMargin
• --dotExpand - transform scale

Displays a runnning timer

• time - current time in milliseconds
• ms - whether to show milliseconds
• short - wont show minutes/hours unless greater than 0
• running - should the timer be progressing