Card Component - Complete Documentation

Table of Contents

- Overview
- Installation
- Basic Usage
- Inputs
- Content Projection
- Usage Examples
- Best Practices

---

Overview

The ngx-st-card component is a styled card wrapper with header, actions, and content areas. Features include:
- Title with optional back navigation
- Create button with custom link
- Action menu and action button support
- History back button
- Configurable body padding
- Material Design styling

---

Installation

``bash
npm install ngx-st-card
`

Import the module:

`typescript
import { StCardModule } from 'ngx-st-card';

@NgModule({
imports: [StCardModule]
})
export class AppModule { }
`

---

Basic Usage

`html

Card content goes here

`

---

Inputs

$3

- Type: string
- Default: undefined
- Description: Title text displayed in the card header.
- Example:
`html
title="User Profile"
title="Product Details"
[title]="dynamicTitle"
`

$3

- Type: string[]
- Default: undefined
- Description: Router link array for the create button. When provided, shows a create button in the header.
- Example:
`html
[createLink]="['/users', 'create']"
[createLink]="['/products', 'new']"
`

$3

- Type: string[]
- Default: undefined
- Description: Router link array for the back button. When provided, shows a back button in the header.
- Example:
`html
[backLink]="['/users']"
[backLink]="['/dashboard']"
`

$3

- Type: boolean
- Default: false
- Description: Shows a back button that uses browser history (Location.back()). Alternative to backLink.
- Example:
`html
[showHistoryBack]="true"
`

$3

- Type: MenuElementModel[]
- Default: undefined
- Description: Array of menu items to display in the actions dropdown menu. Requires ngx-st-dynamic-menu types.
- Example:
`typescript
actionMenu: MenuElementModel[] = [
{ label: 'Edit', icon: 'edit', action: () => this.edit() },
{ label: 'Delete', icon: 'delete', action: () => this.delete() }
];
`
`html
[actionMenu]="actionMenu"
`

$3

- Type: MenuElementModel
- Default: undefined
- Description: Single action button to display in the header (not in dropdown).
- Example:
`typescript
actionButton: MenuElementModel = {
label: 'Save',
icon: 'save',
action: () => this.save()
};
`
`html
[actionButton]="actionButton"
`

$3

- Type: boolean
- Default: false
- Description: Removes top padding from the card body. Useful for tables or other content that needs to start at the top.
- Example:
`html
[noBodyTopPadding]="true"
`

$3

- Type: string
- Default: 'Create'
- Description: Custom label for the create button.
- Example:
`html
createLinkLabel="Add New"
createLinkLabel="New Product"
`

---

Content Projection

The component uses content projection for the card body:

`html

Any HTML content

Components, forms, tables, etc.

`

---

Usage Examples

$3

`typescript
// Component
@Component({
selector: 'app-user-profile',
template:

Name: {{ user.name }}

Email: {{ user.email }}

Role: {{ user.role }}


})
export class UserProfileComponent {
user = {
name: 'John Doe',
email: 'john@example.com',
role: 'Administrator'
};
}
`

$3

`typescript
// Component
@Component({
selector: 'app-user-details',
template:
title="User Details"
[backLink]="['/users']">

User information here...


})
export class UserDetailsComponent { }
`

$3

`typescript
// Component
@Component({
selector: 'app-product-view',
template:
title="Product Details"
[showHistoryBack]="true">

Product content...


})
export class ProductViewComponent { }
`

$3

`typescript
// Component
@Component({
selector: 'app-users-list',
template:
title="Users"
[createLink]="['/users', 'create']"
createLinkLabel="Add User">





})
export class UsersListComponent { }
`

$3

`typescript
// Component
@Component({
selector: 'app-document-view',
template:
title="Document"
[showHistoryBack]="true"
[actionMenu]="documentActions">

Document content...


})
export class DocumentViewComponent {
documentActions: MenuElementModel[] = [
{
label: 'Edit',
icon: 'edit',
action: () => this.editDocument()
},
{
label: 'Download',
icon: 'download',
action: () => this.downloadDocument()
},
{
label: 'Share',
icon: 'share',
action: () => this.shareDocument()
},
{
label: 'Delete',
icon: 'delete',
action: () => this.deleteDocument()
}
];

editDocument(): void {
console.log('Edit document');
}

downloadDocument(): void {
console.log('Download document');
}

shareDocument(): void {
console.log('Share document');
}

deleteDocument(): void {
console.log('Delete document');
}
}
`

$3

`typescript
// Component
@Component({
selector: 'app-form-card',
template:
title="Edit Profile"
[showHistoryBack]="true"
[actionButton]="saveButton">


})
export class FormCardComponent {
profileForm = this.fb.group({
name: [''],
email: ['']
});

saveButton: MenuElementModel = {
label: 'Save Changes',
icon: 'save',
action: () => this.save()
};

constructor(private fb: FormBuilder) {}

save(): void {
if (this.profileForm.valid) {
console.log('Saving:', this.profileForm.value);
}
}
}
`

$3

`typescript
// Component
@Component({
selector: 'app-data-table-card',
template:
title="Products"
[createLink]="['/products', 'create']"
createLinkLabel="New Product"
[noBodyTopPadding]="true">
[data]="products"
[initColumns]="columns">



})
export class DataTableCardComponent {
products = [...];
columns = [...];
}
`

$3

`typescript
// Component
@Component({
selector: 'app-project-details',
template:
[title]="project.name"
[backLink]="['/projects']"
[createLink]="['/projects', project.id, 'tasks', 'create']"
createLinkLabel="Add Task"
[actionMenu]="projectActions"
[actionButton]="primaryAction">

{{ project.description }}

Status: {{ project.status }}

Progress: {{ project.progress }}%

Tasks

{{ task.name }}


})
export class ProjectDetailsComponent {
project = {
id: 1,
name: 'Project Alpha',
description: 'Important project',
status: 'In Progress',
progress: 65,
tasks: [...]
};

primaryAction: MenuElementModel = {
label: 'Complete Project',
icon: 'check_circle',
action: () => this.completeProject()
};

projectActions: MenuElementModel[] = [
{
label: 'Edit Project',
icon: 'edit',
action: () => this.editProject()
},
{
label: 'Export',
icon: 'file_download',
action: () => this.exportProject()
},
{
label: 'Archive',
icon: 'archive',
action: () => this.archiveProject()
},
{
label: 'Delete',
icon: 'delete',
action: () => this.deleteProject()
}
];

completeProject(): void {
console.log('Complete project');
}

editProject(): void {
console.log('Edit project');
}

exportProject(): void {
console.log('Export project');
}

archiveProject(): void {
console.log('Archive project');
}

deleteProject(): void {
console.log('Delete project');
}
}
`

$3

`typescript
// Component
@Component({
selector: 'app-dynamic-card',
template:
[title]="cardTitle"
[showHistoryBack]="true"
[actionMenu]="getActions()">

Content based on {{ entityType }}


})
export class DynamicCardComponent implements OnInit {
entityType = 'user';
entityId = 123;

get cardTitle(): string {
return ${this.entityType} #${this.entityId};
}

ngOnInit(): void {
// Load entity data
}

getActions(): MenuElementModel[] {
return [
{
label: 'Edit',
icon: 'edit',
action: () => this.edit()
},
{
label: 'Delete',
icon: 'delete',
action: () => this.delete()
}
];
}

edit(): void {
console.log('Edit', this.entityType);
}

delete(): void {
console.log('Delete', this.entityType);
}
}
`

---

Best Practices

1. Use descriptive titles:
`html
title="User Profile"
title="Details"
`

2. Choose appropriate navigation:
`html

[backLink]="['/users']"


[showHistoryBack]="true"
`

3. Group related actions in menu:
`typescript
actionMenu = [
{ label: 'Edit', ... },
{ label: 'Duplicate', ... },
{ label: 'Delete', ... }
];
`

4. Use actionButton for primary action:
`typescript
actionButton = { label: 'Save', icon: 'save', ... };
`

5. Remove top padding for tables:
`html
[noBodyTopPadding]="true"
`

6. Provide clear create button labels:
`html
createLinkLabel="Add User"
createLinkLabel="New Product"
`

---

MenuElementModel Interface

When using actionMenu or actionButton:

`typescript
interface MenuElementModel {
label: string; // Button/menu item label
icon?: string; // Material icon name
action?: () => void; // Click handler function
url?: string[]; // Router link (alternative to action)
disabled?: boolean; // Disable the action
color?: 'primary' | 'accent' | 'warn'; // Button color
}
`

---

Common Patterns

$3

Card with create button and table content, no top padding.

$3

Card with back button and action menu for entity operations.

$3

Card with back button and save action button.

$3

Simple card with title and content, no actions.

---

Component Structure

`html


├── Back Button (optional)
├── Title
├── Create Button (optional)
├── Action Button (optional)
└── Action Menu (optional)


└── Your content here

`

---

Styling

The component includes base Material Design card styling. You can override styles:

`css
ngx-st-card {
/ Customize card appearance /
}

ngx-st-card ::ng-deep .card-header {
/ Customize header /
}

ngx-st-card ::ng-deep .card-body {
/ Customize body /
}
``

---

This documentation covers all inputs and usage patterns for the Card component.