0
# Option Highlighting
1

2
The `NgOptionHighlightDirective` provides automatic highlighting of search terms within option text, making it easier for users to see matching content in autocomplete and search scenarios.
3

4
## Capabilities
5

6
### NgOptionHighlight Directive
7

8
Highlights specified search terms within the element's text content by wrapping matches with `<span class="highlighted">` elements.
9

10
```typescript { .api }
11
/**
12
 * Directive for highlighting search terms within option text
13
 * Automatically escapes regex special characters and supports multiple word highlighting
14
 */
15
@Directive({
16
  selector: '[ngOptionHighlight]'
17
})
18
export class NgOptionHighlightDirective implements OnChanges, AfterViewInit {
19
  /** The search term to highlight within the element's text content */
20
  @Input('ngOptionHighlight') term: string;
21
}
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { NgOptionHighlightDirective } from '@ng-select/ng-select';
28

29
@Component({
30
  template: `
31
    <ng-select 
32
      [(ngModel)]="selectedCity"
33
      [searchable]="true"
34
      (search)="onSearch($event)">
35
      <ng-option *ngFor="let city of filteredCities" [value]="city.id">
36
        <span [ngOptionHighlight]="searchTerm">{{ city.name }}</span>
37
      </ng-option>
38
    </ng-select>
39
  `,
40
  imports: [NgOptionHighlightDirective]
41
})
42
export class CitySelectComponent {
43
  searchTerm: string = '';
44
  cities = [
45
    { id: 1, name: 'New York' },
46
    { id: 2, name: 'Los Angeles' },
47
    { id: 3, name: 'Chicago' }
48
  ];
49
  filteredCities = this.cities;
50

51
  onSearch(event: { term: string, items: any[] }) {
52
    this.searchTerm = event.term;
53
    this.filteredCities = event.items;
54
  }
55
}
56
```
57

58
With custom option template:
59

60
```typescript
61
@Component({
62
  template: `
63
    <ng-select [(ngModel)]="selectedUser" [searchable]="true">
64
      <ng-option *ngFor="let user of users" [value]="user.id">
65
        <div class="user-option">
66
          <strong [ngOptionHighlight]="searchTerm">{{ user.name }}</strong>
67
          <small [ngOptionHighlight]="searchTerm">{{ user.email }}</small>
68
        </div>
69
      </ng-option>
70
    </ng-select>
71
  `
72
})
73
export class UserSelectComponent {
74
  searchTerm: string = '';
75
  users = [
76
    { id: 1, name: 'John Doe', email: 'john@example.com' },
77
    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
78
  ];
79
}
80
```
81

82
### Features
83

84
- **Automatic Escaping**: Special regex characters in search terms are automatically escaped
85
- **Case Insensitive**: Highlighting works regardless of case differences
86
- **Multiple Words**: Space-separated terms are treated as alternatives (OR logic)
87
- **Safe HTML**: Uses Angular's Renderer2 for secure DOM manipulation
88
- **CSS Customizable**: Highlighted text is wrapped in `<span class="highlighted">` for styling
89

90
### Styling
91

92
The directive wraps highlighted text with `<span class="highlighted">`. Add CSS to customize appearance:
93

94
```css
95
.highlighted {
96
  background-color: yellow;
97
  font-weight: bold;
98
  color: black;
99
}
100

101
/* Alternative styling */
102
.highlighted {
103
  background-color: #007bff;
104
  color: white;
105
  padding: 1px 3px;
106
  border-radius: 2px;
107
}
108
```
109

110
### Implementation Notes
111

112
- The directive preserves the original text content when no search term is provided
113
- Text highlighting occurs after view initialization and on input changes
114
- The search term can contain multiple words separated by spaces - each word will be highlighted independently
115
- All regex special characters in the search term are properly escaped for safety