#### SM Components

#### Getting Started

- Overview
- Quick start
- Global styling

#### Components

##### Total components

#

# Overview

Component-based design is the cornerstone of the modern UI development process. With rise of more UI frameworks every day, the web platform has a serious issue of fragmentation and portability.

Web components to the rescue! This is the collection of web components (WC here forward) that we use at RanchiMall, especially since we are a framework-less development environment so this was a logical choice.

### Features

- Native and Cross framework support
- Encapsulated style and functionality
- Easy styling
- Adaptive scaling

# Quick Start

1. To start using these components, Select the ones you want to add to your project. You can un-check 'get minified' to get the readable code.
2. Now you can download or copy the source code for selected components. You might get a warning while downloading like this file is not safe, please allow the download as this is caused when downloading files with '.js' extension. These components are 100% safe to use.
3. Link the downloaded js before </body>

       <script src=".../components.js"></script>

Get minified Select all Clear all
Copy source code Download JS file

# Global styling

These components use CSS variables to customize styling. they share some CSS variables that make global styling easier.
Of course you can set these variables at individual component CSS rule set level.

#### Some common CSS variables and their use

#### Variable

#### Use

--accent-color

Color which will be used for denoting active state

--text-color

default text color for all components.
( Use comma separated rgb values. e.g 17, 17, 17 )

--background-color

default background color for all components.
( Use comma separated rgb values. e.g 255, 255, 255 )

--danger-color

Used for error/invalid state

# Buttons

Default button

## Variants

These are styled variations of base component

#### Variant type

#### Example

primary

Primary

outlined

Outlined

no--outline

No outline

#### How to define variant

    <sm-button variant="primary">primary</sm-button>
    <sm-button variant="outlined">outlined</sm-button>
    <sm-button variant="no-outline">no-outline</sm-button>

## States

#### Disabled

To disable the button add disabled attribute.

Disabled

    <sm-button disabled>Disabled</sm-button>

## Attributes

All the native HTML checkbox attributes are valid

#### Attribute

#### Description

disabled (boolean)

Button is disabled by default. all the interactions are disabled

type (string)

Has values submit reset
Can only used withing sm-form to submit or reset the form.

## Styling

CSS variables used to style this component

#### Variable

#### Description

--background

Define background of button. accepts all values of CSS background property

--border-radius

Set curvature at button corners

--padding

Specify padding of button

# Carousel

Carousel is a very common UI component primarily used to display images or slides. This carousel switches user interactions based on type of input devices present. For hover capable devices slides can be scrolled with buttons and on touch enabled devices swipe can be used.

## Interactive demo

### Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Provident, optio.

### Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Provident, optio.

### Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Provident, optio.

### Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Provident, optio.

    <sm-carousel align-items="start" indicator>
        <!-- carousel items -->
    </sm-carousel>

## Custom attributes

These attributes cane used to customize carousel behaviour and features

#### Attribute

#### Description

align-items

Has values start center end Specifies how carousel items should align. default is center.

indicator (boolean)

if added carousel shows dot indicators of carousel items.

## Styling

CSS variables used to style this component

#### Variable

#### Description

--active-indicator-color

Defines background color of active slide indicator

--nav-background-color

Defines background color of carousel navigation buttons

--nav-box-shadow

Defines box shadow of carousel navigation buttons

--nav-icon-fill

Defines fill of arrow icon on carousel navigation buttons

# Checkbox

sm-checkbox supports all the attributes of native HTML5 checkbox

linking some HTML element with sm-checbox using label tag won't work.
Add the element inside the opening and closing checkbox tag.

## Interactive demo

Check this box

## States

#### Checked

To make checkbox checked by default add checked attribute.

Checked checkbox

    <sm-checkbox  checked>
        <div style="margin-left: 0.5rem;">Checked checkbox</div>
    </sm-checkbox>

#### Disabled

To disable the checkbox add disabled attribute.

Disabled checkbox

    <sm-checkbox  disabled>
        <div style="margin-left: 0.5rem;">Disabled checkbox</div>
    </sm-checkbox>

## Attributes

All the native HTML checkbox attributes are valid

#### Attribute

#### Description

checked (boolean)

If present, checkbox is set to checked state as default.

disabled (boolean)

If present checkbox is set to disabled state. all the interactions are disabled

value (string)

Sets value of checkbox which can be accessed by value property with JS

## Styling

CSS variables used to style this component

#### Variable

#### Description

--border-color

Defines color of un-checked checkbox border

--border-radius

Defines border-radius of checkbox square

--height

Defines height of checkbox

--width

Defines width of checkbox

# Copy

## Interactive demo

    <sm-copy value="copy this message"></sm-copy>

## Usage

    <sm-copy id="text_to_copy" value="sample text"></sm-copy>
    <script>
        const textToCopy = document.getElementById('text_to_copy')
        textToCopy.value = 'Different value'; /* Setting value to be copied */
    </script>

## Attributes

#### Attribute

#### Description

value ( string )

Defines content that will be copied when copy button is clicked

## Styling

CSS variables used to style this component

#### Variable

#### Description

--button-background-color

Defines background color of copy button

--button-border-radius

Defines border-radius of copy button

## Supported events

#### Event

#### Description

copy

Fired when text is copied by user.

# File input

<file-input> is essentially native <input type="file"/> with added style.
So every attribute supported by native file input is supported as can be used in exactly same way.

## Interactive demo

Select multiple files

    <file-input multiple>Select multiple files</file-input>

## Attributes

#### Attribute

#### Description

accept

One or more unique file type specifiers describing file types to allow

capture

What source to use for capturing image or video data

files

A FileList listing the chosen files

multiple

A Boolean which, if present, indicates that the user may choose more than one file

# Form

Browser support for web components form validation or form submition is not perfect. so to circumvent this problem <sm-form> can be used.

## Interactive demo

Login

## Supported functions

#### Function

#### Description

reset()

When this function is called upon form element. all the form elements (sm- form components only) will be reset to default state.

## Nested element behaviour

#### Element

#### behaviour

sm-button variant="primary" or type="submit"

Whenever enter is pressed inside an active sm-input, this will fire click event.
This will also change state depending opon validation conditions.

sm-button type="reset"

When clicked, the whole form will reset.

# Hamburger menu

#### Hamburger menu closed

#### Hamburger menu open

## Usage

    <hamburger-menu id="navigation_drawer">

    </hamburger-menu>
    <script>
        const navigationDrawer = document.getElementById('navigation_drawer')
        const navigationDrawerButton = document.getElementById('navigation_drawer_button')
        navigationDrawerButton.addEventListner('click', e => {
            navigationDrawer.open(); // Will open hamburger menu on mobile devices when hidden
        })
    </script>

# Input

## Interactive demo

    <sm-input id="my_input" placeholder="Email" type="email" value="john@doe" animate></sm-input>

## Variants

outlined is only one styled variation. Default is filled which doesn't require variant specified.

    <sm-input placeholder="Name" variant="outlined" animate></sm-input>

## Custom Attributes

All the native HTML input attributes are valid. These are additional attributes which can be used to add more functionality

#### Attribute

#### Description

animate (boolean)

If present, placeholder of input will be animated to occupy space above enterned text instead of vanishing.

error-text (string)

Message specified as value of this attribute will be shown if validation fails.

## Styling

CSS variables used to style this component

#### Variable

#### Description

--background

Defines background property of input. Any valid CSS background values are supported.

--border-radius

Sets border-radius of input.

--icon-gap

Sets space between input icon and input box. Default is "0.5rem"

--font-size

Sets font size of input text. Default is "1rem".

--padding

Sets padding around whole input box including icon.

--width

Sets width of input box.

## Supported functions

#### Function

#### Description

focusIn()

To give focus to this component use this function instead of focus()

reset()

When this function is called value will be set to empty string.

## Custom Setters

#### Function

#### Description

customValidation

If you want to perform custom validation on input value, set the desired validation function.

disabled

Set disabled state to true or false

value

Sets the value of input with JS

    <script>
        /* Setting custom validation function */
        document.getElelementById('my_input').customValidation = myValidation

        function myValidation(inputValue) {
            /* Custom validation logic */
            return Boolean; /* Must return Boolean ( true/ false ) */
        }
    </script>

# Menu

## Interactive demo

first option second option third option

    <sm-menu>
        <menu-option>first option</menu-option>
        <menu-option>second option</menu-option>
        <menu-option>third option</menu-option>
    </sm-menu>

## Custom Attributes

#### Attribute

#### Description

align-options (string)

Specifies alignment of options relative to left or right edge of menu button.
Valid values are left right.

## Supported events

#### Event

#### Description

click

To setup functions on click event. use standard method to add event listeners on options themselves or delegate event on menu component level.

# Notifications

To start using notifications add the <sm-notifications> at top level of markup like just below starting <body> tag.

## Supported functions

#### Function

#### Description

push()

Used to display notifications with two parameters.
Notification text and notification options.

clearAll()

Removes all the notifications present in notification drawer.

## Push() options

#### Property

#### Description

icon (svg)

To display custom icon with notification icon option can be used.

pinned (Boolean)

If set true notifications won't disappear after some time. they need to be dismissed by user manually.

## Interactive demo

push pinned notification

    <sm-notifications id="notification_drawer"></sm-notifications>
    <script>
        const notificationDrawer = document.getElementById('notification_drawer')
        notificationDrawer.push('This is a notification', { pinned: true })
    </script>

# Popup / dialog

Popups are used to show addition UI elements that you may want to hide at first and reveal them when needed.

## Interactive demo

## Title

Lorem ipsum, dolor sit amet consectetur adipisicing elit. Dolore tenetur natus, pariatur beatae veritatis debitis repellat laudantium corporis velit adipisci!

show popup

    <sm-popup id="my_popup">
    <!--Popup content -->
    </sm-popup>

## Usage

    <sm-popup id="my_popup">
        <!--Popup content -->
    </sm-popup>
    <sm-button id="show_popup_button">Show popup</sm-button>
    <script>
        const myPopup = document.getElementById('my_popup')
        document.getElementById('show_popup_button').addEventListener('click', e => {
            myPopup.show({options});
        })
    </script>

## Custom Attributes

#### Attribute

#### Description

open (boolean)

If present, popup will be in opened state by default. useful for development purpose.

## Styling

CSS variables used to style this component

#### Variable

#### Description

--backdrop-background

Defines background property of popup backdrop. Any valid CSS background value is supported.

--border-radius

Defines border-radius of popup dialog box.

--body-padding

Defines padding of popup dialog box.

--height

Defines height of popup dialog box.

--min-height

Defines min-height of popup dialog box.

--width

Defines width of popup dialog box.

--min-width

Defines min-width of popup dialog box.

## Supported functions

#### Function

#### Description

show()

Displays the hidden popup, when called upon specified popup.

hide()

Hides the visible popup, when called upon specified popup

#### Show() options

#### Property

#### Description

pinned ( Boolean )

If set true, opened popup won't be closed when clicked outside the popup area.

## Custom events

#### Event

#### Description

popupopned

Fired when a popup is opened, to access which popup fired the event you can use event.detail.popup within event listener

popupclosed

Fired when a popup is closed, to access which popup fired the event you can use event.detail.popup within event listener

# Radio button

Radio buttons are useful whenever only one option needs to be selected from mutiple options. this functionality can be achieved by assigning same name to the group of radio buttons.
sm-radio supports all the attributes of native HTML5 radio.

linking some HTML element with sm-radio using label tag won't work.
Add the element inside the opening and closing sm-radio tag.

## Interactive demo

On
Off
🤷

    <sm-radio name="abc" value="on" checked>
        <div>  On</div>
    </sm-radio>
    <sm-radio name="abc" value="off">
        <div>  Off</div>
    </sm-radio>
    <sm-radio name="abc" value="🤷">
        <div>  🤷</div>
    </sm-radio>

## States

#### Checked

To make switch turned on by default add checked attribute.

Checked radio button

    <sm-radio checked>
        <div>On switch</div>
    </sm-radio>

#### Disabled

To disable the radio button add disabled attribute.

Disabled radio button

    <sm-radio disabled>
        <div>Disabled switch</div>
    </sm-radio>

## Attributes

All the native HTML radio attributes are valid

#### Attribute

#### Description

checked (boolean)

If present, radio button is set to checked state as default.

disabled (boolean)

If present radio button is set to disabled state. all the interactions are disabled

name (string)

Can be used to group radio buttons with same name. only one radio button will be active in a group.

value (string)

Sets value of radio button which can be accessed by value property with JS

# Select

<sm-select> is very similar to starndatd HTML5 select and it's markup stucture is also identical.

## Interactive demo

option1 option2 option3

    <sm-select>
        <sm-option value="1">option1</sm-option>
        <sm-option value="2">option2</sm-option>
        <sm-option value="3">option3</sm-option>
    </sm-select>

## Usage

    <sm-select id="my_select">
        <sm-option value="1">option1</sm-option>
        <sm-option value="2">option2</sm-option>
        <sm-option value="3">option3</sm-option>
    </sm-select>
    <script>
        const mySelect = document.getElementById('my_select')
        mySelect.addEventListener('change', event => {
            console.log(event.target.value) // logs out value of selected option
        })
    </script>

## States

#### Disabled

To disable the select add disabled attribute.

option1 option2 option3

    <sm-select disabled>
        <!-- Options -->
    </sm-select>

## Supported events

These are the events that will be fired when component state changes

#### Event

#### Description

change

Whenever a different options is selected by user the this event is fired.
You can listen to this event and access the current value with event object event.target.value

# Spinner

Just drop the sm-spinner in markup where you want to show the spinner

    <sm-spinner></sm-spinner>

# Switch

sm-switch supports all the attributes of native HTML5 checkbox

linking some HTML element with sm-switch using label tag won't work.
Add the element inside the opening and closing sm-switch tag.

## Interactive demo

Turn the switch

## States

#### Checked

To make switch turned on by default add checked attribute.

On switch

    <sm-switch checked>
        <div slot="left">
            On switch
        </div>
    </sm-switch>

#### Disabled

To disable the switch add disabled attribute.

Disabled checkbox

    <sm-switch disabled>
        <div slot="left">
            Disabled switch
        </div>
    </sm-switch>

## Attributes

All the native HTML checkbox attributes are valid

#### Attribute

#### Description

checked (boolean)

If present, switch is set to checked state as default.

disabled (boolean)

If present switch is set to disabled state. all the interactions are disabled

value (string)

Sets value of switch which can be accessed by value property with JS

# Chips

This is a modern interpretation of classical HTML select tag. More suitable for touch devices,

## Interactive demo

Sort by Relevance Popularity Price Rating

    <sm-chips id="sort_by">
        <sm-chip value="relevance" selected>Relevance</sm-chip>
        <sm-chip value="popularity">Popularity</sm-chip>
        <sm-chip value="price">Price</sm-chip>
        <sm-chip value="rating">Rating</sm-chip>
    </sm-chips>

## Custom attributes

#### Attribute

#### Description

multiline ( Boolean )

If present, options will wrap around instead of overflowing horizontally.

## Styling

CSS variables used to style this component

#### Variable

#### Description

--gap

Defines space between options. Default is "0.5rem".

## Supported events

These are the events that will be fired when component state changes

#### Event

#### Description

change

Whenever a different options is selected by user the this event is fired.
You can listen to this event and access the current value with event object event.target.value

## Usage

    <sm-chips id="sort_by">
        <sm-chip value="relevance" selected>Relevance</sm-chip>
        <sm-chip value="popularity">Popularity</sm-chip>
        <sm-chip value="price">Price</sm-chip>
        <sm-chip value="rating">Rating</sm-chip>
    </sm-chips>
    <script>
        const sortBy = document.getElementById('sort_by')
        sortBy.addEventListener('change', event => {
            console.log(event.target.value) // logs out value of selected option
        })
    </script>

# Tabs

This component can be used sub-page navigation.

## Interactive demo

Audio Video

### Audio

Lorem ipsum, dolor sit amet consectetur adipisicing elit. Exercitationem esse quod quae repellat qui. Expedita fugiat voluptates beatae itaque corporis!

### Video

Lorem ipsum, dolor sit amet consectetur adipisicing elit. Exercitationem esse quod quae repellat qui. Expedita fugiat voluptates beatae itaque corporis!

## Usage

    <sm-tab-header target="tab1">
        <sm-tab>
            tab name
        </sm-tab>
        <sm-tab>
            tab name
        </sm-tab>
    </sm-tab-header>
    <sm-tab-panels id="tab1">
        <section>
            <!-- Panel content -->
        </section>
        <section>
            <!-- Panel content -->
        </section>
    </sm-tab-panels>

There are three components that together make the tabs components.

1. sm-tab-header
2. sm-tab
3. sm-tab-panels

### sm-tab-header

This is the first half of tabs that include the tabs header and actual tab buttons.

    <sm-tab-header variant="tab" target="tab2">
        <sm-tab>Audio</sm-tab>
        <sm-tab>Video</sm-tab>
    </sm-tab-header>

## Supported attributes

#### Attribute

#### Description

variant ( string )

Specifies variant of sm-tab-header. Only value can be tab

target ( string )

Pass in the ID of respective sm-tab-panels to link them. This is how sm-tab-header communicates with sm-tab-panel on which tab or panel should be displayed.

## Variants

tab is the only other variant than default style.

Audio Video

### Audio

Lorem ipsum, dolor sit amet consectetur adipisicing elit. Exercitationem esse quod quae repellat qui. Expedita fugiat voluptates beatae itaque corporis!

### Video

Lorem ipsum, dolor sit amet consectetur adipisicing elit. Exercitationem esse quod quae repellat qui. Expedita fugiat voluptates beatae itaque corporis!

    <sm-tab-header variant="tab" target="tab2">
        <sm-tab>Audio</sm-tab>
        <sm-tab>Video</sm-tab>
    </sm-tab-header>

# Tags input

This component has a very specific use case and that is for accepting tags. Each time user presses enter or space, a new tag is created. Only unique values are allowed.

## Interactive demo

    <tags-input placeholder="Add tags..."></tags-input>

## Attributes

#### Attribute

#### Description

placeholder ( string )

Define some string to let user know which kind of input is required.

limit ( number )

Set a limit of tags that will be accepted atmost

## Styling

CSS variables used to style this component

#### Variable

#### Description

--background

Defines background of tags-input. Any valid CSS background property values are supported.

--border-radius

Defines border-radius of tags-input

## Supported functions

#### Function

#### Description

focusIn()

To give focus to this component use this function instead of focus()

reset()

When this function is called value will be set to empty string.

## Usage

    <tags-input id="get_tags" placeholder="Add tags..."></tags-input>
    <script>
        const getTags = document.getElementById('get_tags')
        console.log(getTags.value); /* returns an array of string that are user input */
    </script>

# Textarea

Textarea is suitable component where multiline input is required. you can either specify the number of lines textarea should expand or let the textarea expand according to user input until a max-height is reached.

## Interactive demo

    <sm-textarea id="my_textarea" placeholder="Add some text here..." rows="4"></sm-textarea>

## Variants

outlined is only one styled variation. Default is filled which doesn't require variant specified.

    <sm-textarea placeholder="This is a textarea" variant="outlined"></sm-textarea>

## Supported Attributes

All the native HTML textarea attributes are valid.

#### Attribute

#### Description

disabled (boolean)

If present, all the interactions will be blocked.

rows (number)

Sets the number of rows textarea will be expanded by default. Default is "1".

value (string)

Sets the default value of textarea.

## Styling

CSS variables used to style this component

#### Variable

#### Description

--background

Defines background textarea. Any valid CSS background property values are supported.

--border-radius

Defines border-radius of textarea

--max-height

Defines max-height to which textarea is allowed to expand. Default is "8rem"

## Supported functions

#### Function

#### Description

focusIn()

To give focus to this component use this function instead of focus()

reset()

When this function is called value will be set to empty string.

## Setters

#### Function

#### Description

disabled

Set disabled state to true or false

value

Sets the value of textarea with JS

## Usage

    <sm-textarea placeholder="This is a textarea" id="my_textarea"></sm-textarea>
    <script>
        const myTextarea = document.getElelementById('my_textarea')
        myTextarea.value = 'some string'; /* setting value of textarea */

        myTextarea.addEventListener('input', event => {
            const value = event.target.value; /* accessing value of textarea */
        })
    </script>

# Text field

This component can be used in scenarios where you need to display a name or something that user should be able to edit directly in-place instead of going to other UI element.

## Interactive demo

## Usage

    <text-field id="name_field" value="John doe"></text-field>
    <script>
        const nameField = document.getElementById('name_field')
        nameField.addEventListener('change', event => {
            console.log(event.target.value) // logs out new value set by user
            console.log(nameField.value) // Accessing value directly with getter
        })
    </script>

## Custom attributes

#### Attribute

#### Description

disabled ( Boolean )

If present, text can't be edited.

value ( string )

Set initial text that can be edited by user.

## Supported events

#### Event

#### Description

change

Fired when text changes are saved by user.

# Theme toggle

Use theme-toggle to create light/dark theme easily with CSS variables.

When this is toggled by user the component changes the custom data attribute data-theme="" on HTML body tag to either light or dark

By default theme is set to OS level preferred-color-scheme ( supported by Android, iOS, Windows and MacOS ).

## Interactive demo

## HTML

    <theme-toggle></theme-toggle>

## CSS

    <style>
        body ,
        body *{
            /* Set CSS variables according to light theme or default theme*/
            --accent-color: #0D7377;
            --text-color: 17, 17, 17;
            --background-color: 255, 255, 255;
            --danger-color: red;
        }
        body[data-theme='dark'],
        body[data-theme='dark'] *{
            /* Set CSS variables according to dark theme */
            --accent-color: #32E0C4;
            --text-color: 240, 240, 240;
            --text-color-light: 170, 170, 170;
            --background-color: 10, 10, 10;
            --danger-color: rgb(255, 106, 106);
        }
        body{
            color: rgba(var(--text-color), 1);
            background: rgba(var(--background-color), 1);
        }
    </style>

## Styling

CSS variables used to style this component

#### Variable

#### Description

--height

Defines height of toggle button

--width

Defines width of toggle button

## Custom events

These are the events that will be fired when component state changes

#### Event

#### Description

themechange

Whenever theme is toggled by user the themechange event is fired.
You can listen to this event and access the current value of toggle with event object event.detail.theme

    <theme-toggle id="my_theme_toggle"></theme-toggle>
    <script>
        const myThemeToggle = document.getElementById('my_theme_toggle')
        myThemeToggle.addEventListener('themechange', event => {
            console.log(event.detail.theme) // logs out current theme ( light / dark )
        })
    </script>