@kuro-samurai/ngx-samurai-button

Samurai Button

Make your app stylish with pre-styled buttons

Features Overview

This directive has:

• 3 Variations
• 3 Content Types
• 7 Hover Effects
• 3 Border Radius Styles
• 2 States
• 10 Pre-styled Buttons
• Automatic text and icon and hover color detection
• Support for Angular Internationalization
• Support for ARIA
• Material Icon Font (super light weight)

The style of the button is based on UI/UX guidelines. You can set
filled, outlined or texted variations for it or change content type
to text, text and icon or just icon to get the right attention and priority you need.

Installation

This directive supports Angular 16 and higher

Run the code below in your project terminal:

ng add @kuro-samurai/ngx-samurai-button

This command will install material icon font package.
The samurai-styles.css file will be created in the root
of your project and it will be added to your angular.json
project styles

Use

Selector: samuraiButton
Type: Standalone

1. Import the directive

   • If your component is standalone, import the directive to your
     @Component decorator:

     @Component({
       //...
       standalone: true,
       imports: [CommonModule, SamuraiButtonsComponent],
       //...
     })

   • Else import it to your component's module:

     @NgModule({
       //...
       imports: [CommonModule, SamuraiButtonsComponent],
       //...
     })

2. Then in your component import class SamuraiButtonConfig and use its constructor:

   public buttonConfig = new SamuraiButtonConfig()

   In the parenthesis use shortcut ctrl + space or command + space to see available values.
   All parameters have default values so you don't need to pass all values.

   Note: Refer to properties table below for values and defaults.
   You can either pass each property individually or pass
   config object, If you do both, values in config object will overwrite
   individual values!

3. Pass the config object to directive input:

   <button samuraiButton [config]="buttonConfig">Samurai</button>

Button With Action

To make button do a certain action everytime user clicks on it,
you can pass a function to it like this:

1. Declare a method in parent component:

   public foo = () => console.log("action foo")

2. Then pass it to property btnAction:

   <button samuraiButton [config]="buttonConfig" [btnAction]="foo">Samurai</button>

If you have complex action to happen after button click,
bind your action to event click like this:

<button samuraiButton [config]="buttonConfig" (click)="foo()">Samurai</button>

Using Pre-Styled Button

Assign one of the values in properties table blow to property (input) preStyled:

<button samuraiButton preStyled="PRIMARY_TEXT">Samurai</button>

More pre-styled buttons will be added soon.

Warning: If you pass both preStyled and config, values in config has priority.

Note: you can overwrite styles with css or add additional styles to button like changing padding, shadow and .etc

Preview

For Live demo visit Github page for Samurai UI (Beta)

Properties (Inputs)

Property	Description	Values	Default
config	An object of type SamuraiButtonConfig that has all properties in this table except preStyled. Pass an instance of it to button to configure all button properties quickly.	instanceof SamuraiButtonConfig	null
preStyled	Set it to any available pre styled buttons for a quick config; Still you need to pass id and text to button.	'PRIMARY_TEXT', 'ACCENT_TEXT', 'SUCCESS_TEXT', 'WARNING_TEXT', 'DANGER_TEXT', 'PRIMARY_ICON', 'ACCENT_ICON', 'SUCCESS_ICON', 'WARNING_ICON', 'DANGER_ICON'	null
variation	Overall style of button based on UI/UX guidelines that controls emphesize and priority of the button.	'FILLED', 'OUTLINED', 'CONTENT_ONLY'	'FILLED'
content	Set Content type of the button to be text, text and icon or just icon.	'TEXT', 'TEXT_ICON', 'ICON'	'TEXT'
hoverStyle	Set button hover style. currently it has 7 different styles and more styles will be added.	'LEFT_TO_RIGHT', 'BOTH_SIDES', 'SHUTTER_UP', 'SHUTTER_DOWN', 'GLOW', 'NEON_BORDER', 'FILL', 'NONE'	'NONE'
borderRadius	Set button border radius based on UI/UX guidelines.	'NORMAL', 'ROUND', 'SHARP'	'NORMAL'
state	Set button state to either enabled or disabled. the disabled state will have no hover effect and has a gray shade over it.	'ENABLED', 'DISABLED'	'ENABLED'
colorDetection	Control auto text and icon color detection feature when variation is 'FILLED' based on background color you passed.	true, false	true
hoverColorDetection	Control auto hover color detection feature. The button AI 😉 will pick a darker shade of background color when hover style is 'LEFT_TO_RIGHT' | 'RIGHT_TO_LEFT' | 'BOTH_SIDES' | 'SHUTTER_UP' | 'SHUTTER_DOWN'	boolean	true
i18n	Setting up button for angular i18n (Internationalization) feature. Read Angular Internationalization	boolean	true
icon	set button icon based on material icons names. Just pass icon name to this property. Refer to Material Icon Repository.	Any Material Icon	'favorite'
iconStyle	Set icon style based on material icon styles.	'filled', 'outlined', 'round', 'sharp', 'two-tone'	'filled'
color	Set text and icon color for the button. If color detection is enabled just pass background color.	any color string in format of hexadecimal	'#000000'
backgroundColor	Set background color of the button.	any color string in format of hexadecimal	'#ffffff'
hoverColor	Set button hover effect color. If hover color detection is enabled just pass background color.	any color string in format of hexadecimal	'#0000aa'

Related Resources

This directive is part of Samurai UI project.

Future Plans

The following features will be added soon:

• Setting up a live demo ✅
• A few pre-defined button styles to quickly choose between them ✅
• Passing a single config object to button ✅
• Passing a function to button that executes on button click ✅
• Automatically detecting right text color for button based on background color ✅
• Automatically detecting right hover effect color based on
  color and background color ✅
• Adding support for i18n (Internationalization) ✅
• Implementing ARIA support for people using AT ✅
• Transforming component to directive for better developer exprience ✅

Developer Words

I learned a lot from other developers on the web. Now I want to return
the love to software developers community. I plan to make a UI kit for
angular and this package is one of many packages I will publish on npm.

Contributors

• Developer: Amir Allahdadian
  • Email: [e-mail]
  • Whats App: [phone]
  • Discord: -a-