https://github.com/kapilkumar0037/ngx-custom-controls
https://github.com/kapilkumar0037/ngx-custom-controls
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/kapilkumar0037/ngx-custom-controls
- Owner: kapilkumar0037
- Created: 2025-01-11T16:38:02.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-05-03T10:52:49.000Z (6 months ago)
- Last Synced: 2025-05-03T11:33:01.442Z (6 months ago)
- Language: TypeScript
- Size: 429 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-angular - ngx-custom-controls - Angular library, which provides a powerful base directive (`BaseCvaImplementationDirective<T>`) that implements both `ControlValueAccessor` and `Validator` interfaces, making it easy to create custom form controls with built-in validation support for template-driven and reactive forms. (Third Party Components / Forms)
- fucking-awesome-angular - ngx-custom-controls - Angular library, which provides a powerful base directive (`BaseCvaImplementationDirective<T>`) that implements both `ControlValueAccessor` and `Validator` interfaces, making it easy to create custom form controls with built-in validation support for template-driven and reactive forms. (Third Party Components / Forms)
- trackawesomelist - ngx-custom-controls (⭐1) - Angular library, which provides a powerful base directive (`BaseCvaImplementationDirective<T>`) that implements both `ControlValueAccessor` and `Validator` interfaces, making it easy to create custom form controls with built-in validation support for template-driven and reactive forms. (Recently Updated / [May 04, 2025](/content/2025/05/04/README.md))
README
# NGX Custom Controls
Angular library which provides a powerful base directive (`BaseCvaImplementationDirective`) that implements both `ControlValueAccessor` and `Validator` interfaces, making it easy to create custom form controls with built-in validation support. Every custom control implemented by extending the base directive will support both template-driven and reactive forms. Library also provides basic control components created using base directive and bootstrap css.
If you find this library helpful, please consider giving it a ⭐ on [GitHub](https://github.com/kapilkumar0037/ngx-custom-controls)!
## Why Use This Library?
- **Simplified Custom Control Creation**: Create your own form controls by extending the base directive, eliminating the need to implement complex form control interfaces manually
- **Type-Safe**: Fully generic implementation allows you to specify the type of value your control will handle
- **Framework Agnostic**: Works seamlessly with both template-driven and reactive forms
- **Validation Made Easy**: We can use
- **DRY Principle**: The base directive handles all the boilerplate code for form integration
## Features
- 🎯 Framework agnostic form controls
- ✅ Built-in validation support with custom messages
- 🔄 Two-way binding support
- 🎨 Customizable styling
- 📦 Lightweight and tree-shakeable
- 🛡️ Written in TypeScript with strict type checking
- 🔧 Extensible base directive for custom controls
- 📝 Built-in form state tracking (touched, dirty, etc.)
## Installation
```bash
npm install ngx-custom-controls
```
## Basic Usage
Import the desired components in your module or standalone component:
```typescript
import { CustomInputComponent } from 'ngx-custom-controls';
@Component({
// ...
imports: [CustomInputComponent]
})
```
### Template Usage Example
```typescript
@Component({
template: `
`
})
export class ExampleComponent {
email = '';
emailValidators = [
{
validator: Validators.required,
message: 'Email is required'
},
{
validator: Validators.email,
message: 'Please enter a valid email'
}
];
}
```
We just need to write all applicable validators and provide it to the control and everything else will be handled by the directive.
## Creating Custom Controls
You can create your own form controls by extending the `BaseCvaImplementationDirective`:
```typescript
import { Component, input } from '@angular/core';
import { NgClass } from '@angular/common';
import { cvaProviders } from '../../shared/providers/cva-providers';
import { BaseCvaImplementationDirective } from '../../shared/directives/base-cva-implementation.directive';
import { ValidationMessagesComponent } from '../../shared/components/validation-messages/validation-messages.component';
@Component({
selector: 'ngcc-custom-input',
imports: [NgClass, ValidationMessagesComponent],
standalone: true,
templateUrl: './custom-input.component.html',
providers: [...cvaProviders(CustomInputComponent)]
})
export class CustomInputComponent extends BaseCvaImplementationDirective {
styleClass = input('form-control');
placeholder = input('Enter');
type = input('text');
ngOnInit() {
this.value = '';
}
}
```
In most cases you need not to write any code in your control it's only when you need to override something.
## Usage in parent component
It's time to use your component now
### Reactive form example
```html
Age
```
```typescript
ageForm = new FormGroup({
age: new FormControl(22)
});
ageValidators = [
{
validator: Validators.required,
message: 'Age is required'
},
{
validator: Validators.min(18),
message: 'Must be at least 18 years old'
},
{
validator: Validators.max(100),
message: 'Must be less than 100 years old'
}
];
```
You se we have just added applicable validators which can also be shared using shared validator class.
This example demonstrates:
- Creating a custom input component supporting dynamic "type", placeholder and css class
- Number type input to create age input box.
- Integration with reactive forms using `formControlName`
- Custom value parsing
- Bootstrap validation styling
- Multiple validators with custom messages
### Template driven form example
```html
Age
```
```typescript
age:number;
//Same validators used for reactive form control
ageValidators = [
{
validator: Validators.required,
message: 'Age is required'
},
{
validator: Validators.min(18),
message: 'Must be at least 18 years old'
},
{
validator: Validators.max(100),
message: 'Must be less than 100 years old'
}
];
```
## Base Directive Properties
The `BaseCvaImplementationDirective` provides:
### Inputs
- `validators`: Array of `ValidatorWithMessage[]`
- `name`: Control name
- `controlId`: Unique identifier
### Properties
- `value`: Current control value
- `validationErrors`: Current validation errors
- `errorMessages`: Array of error messages
- `isTouched`: Touch state
- `isDirty`: Dirty state
### Methods
- `onInputChange(value: T)`: Handle value changes
- `markAsTouched()`: Mark control as touched
- `runValidators()`: Execute validation
## Validation
Define validators with custom messages:
```typescript
const validators = [
{
validator: Validators.required,
message: 'This field is required'
},
{
validator: Validators.minLength(3),
message: 'Minimum length is 3 characters'
}
];
```
## Components included in library created with Bootstrap css
- Custom input component
- Custom select component
- Custom range component
- Custom Date picker components
- Custom Checkbox
- Custom Radio
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.