0
# Image Utilities
1

2
Image utilities provide control over background image properties including repeat patterns, sizing behavior, and positioning. These utilities are essential for managing background images in responsive designs.
3

4
## Capabilities
5

6
### Background Repeat
7

8
Control how background images repeat within their containers.
9

10
```scss { .api }
11
.bg-repeat { background-repeat: repeat; }
12
.bg-no-repeat { background-repeat: no-repeat; }
13
.bg-repeat-x { background-repeat: repeat-x; }
14
.bg-repeat-y { background-repeat: repeat-y; }
15
.bg-repeat-round { background-repeat: round; }
16
.bg-repeat-space { background-repeat: space; }
17
```
18

19
### Background Size
20

21
Control the sizing behavior of background images.
22

23
```scss { .api }
24
.bg-auto { background-size: auto; }
25
.bg-cover { background-size: cover; }
26
.bg-contain { background-size: contain; }
27
```
28

29
### Background Position
30

31
Control the positioning of background images within their containers.
32

33
```scss { .api }
34
.bg-bottom { background-position: bottom; }
35
.bg-center { background-position: center; }
36
.bg-left { background-position: left; }
37
.bg-left-bottom { background-position: left bottom; }
38
.bg-left-top { background-position: left top; }
39
.bg-right { background-position: right; }
40
.bg-right-bottom { background-position: right bottom; }
41
.bg-right-top { background-position: right top; }
42
.bg-top { background-position: top; }
43
```
44

45
## Usage Examples
46

47
### Hero Banner with Cover Image
48

49
```html
50
<div class="h-screen bg-cover bg-center bg-no-repeat" 
51
     style="background-image: url('hero-background.jpg')">
52
  <div class="flex align-items-center justify-content-center h-full">
53
    <h1 class="text-white text-6xl font-bold">Welcome</h1>
54
  </div>
55
</div>
56
```
57

58
### Card with Background Pattern
59

60
```html
61
<div class="p-4 bg-repeat bg-top" 
62
     style="background-image: url('pattern.png')">
63
  <h3 class="text-lg font-semibold">Card Title</h3>
64
  <p class="text-color-secondary">Card content with background pattern</p>
65
</div>
66
```
67

68
### Image Gallery Thumbnails
69

70
```html
71
<div class="grid">
72
  <div class="col-3">
73
    <div class="aspect-ratio-1x1 bg-cover bg-center border-round"
74
         style="background-image: url('thumb1.jpg')">
75
    </div>
76
  </div>
77
  <div class="col-3">
78
    <div class="aspect-ratio-1x1 bg-contain bg-center bg-no-repeat border-round"
79
         style="background-image: url('thumb2.jpg')">
80
    </div>
81
  </div>
82
</div>
83
```
84

85
### Decorative Elements
86

87
```html
88
<!-- Repeating border pattern -->
89
<div class="border-top-1 bg-repeat-x bg-top" 
90
     style="background-image: url('border-pattern.svg')">
91
  Content with decorative top border
92
</div>
93

94
<!-- Corner accent -->
95
<div class="relative p-4 bg-right-top bg-no-repeat"
96
     style="background-image: url('corner-accent.svg')">
97
  <h4>Card with corner decoration</h4>
98
  <p>Content here</p>
99
</div>
100
```
101

102
## Usage Guidelines
103

104
**Background Size:**
105
- `bg-cover`: Image covers entire container, may crop parts of image
106
- `bg-contain`: Image fits entirely within container, may leave empty space
107
- `bg-auto`: Image displays at its natural size
108

109
**Background Repeat:**
110
- `bg-no-repeat`: Best for hero images and unique graphics
111
- `bg-repeat`: Good for seamless patterns and textures
112
- `bg-repeat-x`: Ideal for horizontal borders and dividers
113
- `bg-repeat-y`: Useful for vertical sidebar patterns
114
- `bg-repeat-round`: Scales image to avoid partial tiles
115
- `bg-repeat-space`: Distributes repeated images evenly
116

117
**Background Position:**
118
- Use specific positions (`bg-left-top`, `bg-right-bottom`) for precise alignment
119
- `bg-center` is most common for focal point images
120
- Corner positions work well for decorative elements
121

122
## Responsive Variants
123

124
All image utilities support responsive variants:
125

126
- `sm:bg-cover` - Apply background sizing on small screens and up
127
- `md:bg-center` - Apply background positioning on medium screens and up
128
- `lg:bg-no-repeat` - Apply background repeat on large screens and up
129
- `xl:bg-contain` - Apply background sizing on extra large screens and up