Skip to content
This repository was archived by the owner on Jun 8, 2026. It is now read-only.

Commit ed89d86

Browse files
simeonoffsimeonoff
authored
Merge branch 'vnext' into apetrov/add-roundness-topic-vnext
2 parents 6ab19ec + d7de373 commit ed89d86

7 files changed

Lines changed: 289 additions & 9 deletions

File tree

‎en/components/.DS_Store‎

-18 KB
Binary file not shown.

‎en/components/display-density.md‎

Lines changed: 58 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -46,35 +46,84 @@ igx-input-group {
4646
}
4747
```
4848

49-
## Incorporating size in your own components and layouts
49+
## Understanding Size with CSS Custom Properties
5050

51-
Ignite UI for Angular exposes a few Sass functions and a mixin that allow you to implement layouts that react to changes of the `--ig-size` CSS property.
51+
The sizing system in Ignite UI works through a set of CSS custom properties that automatically adjust component dimensions and spacing. When you change the `--ig-size` property, components automatically detect this change and apply the appropriate sizing values.
5252

53-
Here's an example on how we can make an element change its width and height based on the value of `--ig-size`.
53+
### Size Detection Variables
5454

55+
Components use several CSS custom properties to detect and respond to size changes:
56+
57+
- `--component-size` - Maps the global `--ig-size` to a numeric value (1=small, 2=medium, 3=large)
58+
- `--is-small` - Set to 1 when component is small-sized, 0 otherwise
59+
- `--is-medium` - Set to 1 when component is medium-sized, 0 otherwise.
60+
- `--is-large` - Set to 1 when component is large-sized, 0 otherwise.
61+
62+
These variables are automatically calculated using mathematical CSS expressions and change whenever `--ig-size` is modified.
63+
64+
### Size Constants
65+
66+
The theming system defines three size constants:
67+
68+
- `--ig-size-small` (value: 1)
69+
- `--ig-size-medium` (value: 2)
70+
- `--ig-size-large` (value: 3).
71+
72+
## Incorporating Size in Your Own Components
73+
74+
You can make your custom components responsive to size changes using Ignite UI's Sass utilities. These utilities generate the necessary CSS custom properties and mathematical expressions behind the scenes.
75+
76+
### Using the Sizable Mixin and Function
77+
78+
Here's how to create a component that responds to the global size setting:
5579

5680
```html
57-
<div class="my-elem"></div>
81+
<div class="my-responsive-element"></div>
5882
```
5983

6084
```scss
6185
@use "igniteui-angular/theming" as *;
6286

63-
.my-elem {
64-
// Make the element sizable
87+
.my-responsive-element {
88+
// The sizable mixin sets up size detection CSS custom properties
6589
@include sizable();
6690

67-
// Define the default size of the element and hook it to the `--ig-size` property
91+
// Connect to the global size system
6892
--component-size: var(--ig-size, var(--ig-size-large));
6993

70-
// Define sizes for small (10px), medium (20px), and large (30px)
94+
// Use the sizable function for responsive sizing
7195
--size: #{sizable(10px, 20px, 30px)};
7296
width: var(--size);
7397
height: var(--size);
7498
}
7599
```
76100

77-
Now any time the value of `--ig-size` changes, `.my-elem` will change its size.
101+
### How the Sizable System Works Behind the Scenes
102+
103+
When you use `@include sizable()`, it generates CSS custom properties that detect the current component size:
104+
105+
```css
106+
.my-responsive-element {
107+
--is-large: clamp(0, (var(--component-size, 1) + 1) - var(--ig-size-large, 3), 1);
108+
--is-medium: min(
109+
clamp(0, (var(--component-size, 1) + 1) - var(--ig-size-medium, 2), 1),
110+
clamp(0, var(--ig-size-large, 3) - var(--component-size, 1), 1)
111+
);
112+
--is-small: clamp(0, var(--ig-size-medium, 2) - var(--component-size, 1), 1);
113+
}
114+
```
115+
116+
The `sizable(10px, 20px, 30px)` function generates a CSS expression that automatically selects the appropriate value:
117+
118+
```css
119+
--size: max(
120+
calc(var(--is-large, 1) * 30px),
121+
calc(var(--is-medium, 1) * 20px),
122+
calc(var(--is-small, 1) * 10px)
123+
);
124+
```
125+
126+
This mathematical approach using `clamp()`, `min()`, `max()`, and `calc()` functions allows components to automatically switch between size values based on the current `--ig-size` setting.
78127

79128
## API References
80129
<div class="divider"></div>

‎en/components/grids_templates/sizing.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,96 @@ The difference is that for the child grid, when `height` is set to percentages,
266266
---
267267
}
268268

269+
## Grid Cell Spacing Control
270+
271+
The [**@@igxName**]({environment:angularApiUrl}/classes/@@igTypeDoc.html) automatically adapts its internal spacing based on the [size](display-density.md) setting. You can further customize the padding and margins in grid header and body cells using CSS custom properties for spacing control.
272+
273+
### Global Grid Spacing
274+
275+
To reduce or increase spacing across all grid cells in your application:
276+
277+
```css
278+
/* Reduce all grid spacing by 20% */
279+
igx-grid {
280+
--ig-spacing: 0.8;
281+
}
282+
283+
/* Increase spacing for better touch accessibility */
284+
igx-grid {
285+
--ig-spacing: 1.2;
286+
}
287+
```
288+
289+
### Grid-Specific Spacing
290+
291+
To adjust spacing for a specific grid instance:
292+
293+
```css
294+
/* Make a particular grid more compact */
295+
.my-compact-grid {
296+
--ig-spacing: 0.6;
297+
}
298+
299+
/* Give a specific grid more breathing room */
300+
.my-spacious-grid {
301+
--ig-spacing: 1.4;
302+
}
303+
```
304+
305+
### Directional Spacing Control
306+
307+
You can control horizontal and vertical spacing independently:
308+
309+
```css
310+
/* Reduce only horizontal spacing (left/right padding) */
311+
.my-grid {
312+
--ig-spacing-inline: 0.5;
313+
--ig-spacing-block: 1.0; /* Keep vertical spacing normal */
314+
}
315+
316+
/* Adjust vertical spacing for tighter row spacing */
317+
.my-grid {
318+
--ig-spacing-inline: 1.0; /* Keep horizontal spacing normal */
319+
--ig-spacing-block: 0.7; /* Reduce vertical spacing (if applicable) */
320+
}
321+
```
322+
323+
### Size-Specific Spacing
324+
325+
Different spacing multipliers can be applied based on the grid's display density:
326+
327+
```css
328+
.my-grid {
329+
/* Compact density gets very tight spacing */
330+
--ig-spacing-small: 0.5;
331+
332+
/* Medium density uses normal spacing */
333+
--ig-spacing-medium: 1.0;
334+
335+
/* Comfortable density gets extra spacing */
336+
--ig-spacing-large: 1.3;
337+
}
338+
```
339+
340+
### Header vs Body Cell Spacing
341+
342+
While the spacing properties affect both header and body cells, you can target them specifically if needed:
343+
344+
```css
345+
/* Reduce padding in header cells specifically */
346+
.my-grid igx-grid-header {
347+
--ig-spacing: 0.7;
348+
}
349+
350+
/* Adjust spacing in data cells */
351+
.my-grid igx-grid-cell {
352+
--ig-spacing: 0.9;
353+
}
354+
```
355+
356+
> [!Note]
357+
> These spacing adjustments work in conjunction with the grid's display density. The spacing multipliers are applied to the base spacing values that are already determined by whether the grid is in compact, cozy, or comfortable density mode.
358+
269359
## API References
270360

271361
* [@@igxNameComponent API]({environment:angularApiUrl}/classes/@@igTypeDoc.html)

‎en/components/themes/.DS_Store‎

-6 KB
Binary file not shown.

‎en/components/themes/sass/.DS_Store‎

-6 KB
Binary file not shown.

‎en/components/themes/spacing.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: Spacing | Ignite UI for Angular
3+
_description: The Ignite UI for Angular provides a way of adjusting paddings and margins with ease on application or component level.
4+
_keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Components, Native Angular Controls, Native Angular Components Library, spacing, padding, margin
5+
---
6+
7+
# Spacing
8+
9+
Spacing configuration can significantly improve the visual representation of large amounts of data. In Ignite UI for Angular, we provide a pre-defined set of options for adjusting paddings and margins.
10+
11+
Instead of using fixed values, we use CSS custom properties to adjust the spacing on an application or a component level.
12+
13+
## How Spacing Works
14+
15+
Ignite UI for Angular provides a sophisticated spacing system that scales dynamically based on component sizes (small, medium, large). The spacing system is built around CSS custom properties that allow you to control spacing at a global or component level without writing custom CSS.
16+
17+
## The Relationship Between Sizing and Spacing
18+
19+
The spacing system in Ignite UI is closely tied to component sizing. Components can have three different sizes:
20+
- **Small** - Compact spacing for dense layouts
21+
- **Medium** - Default balanced spacing.
22+
- **Large** - Comfortable spacing for touch-friendly interfaces
23+
24+
The spacing automatically adapts based on which size is active, ensuring consistent visual hierarchy throughout your application.
25+
26+
## Core CSS Custom Properties
27+
28+
The spacing system revolves around several key CSS custom properties:
29+
30+
### Global Spacing Properties
31+
32+
- `--ig-spacing` - The base spacing multiplier (default: 1)
33+
- `--ig-spacing-small` - Spacing for small-sized components
34+
- `--ig-spacing-medium` - Spacing for medium-sized components.
35+
- `--ig-spacing-large` - Spacing for large-sized components
36+
37+
### Directional Spacing Properties
38+
39+
- `--ig-spacing-inline` - Controls horizontal spacing
40+
- `--ig-spacing-block` - Controls vertical spacing
41+
- `--ig-spacing-inline-small` - Horizontal spacing for small components
42+
- `--ig-spacing-inline-medium` - Horizontal spacing for medium components
43+
- `--ig-spacing-inline-large` - Horizontal spacing for large components
44+
- `--ig-spacing-block-small` - Vertical spacing for small components
45+
- `--ig-spacing-block-medium` - Vertical spacing for medium components
46+
- `--ig-spacing-block-large` - Vertical spacing for large components
47+
48+
## Size Detection Variables
49+
50+
Components use CSS custom properties to automatically detect their current size:
51+
52+
- `--is-small` - Set to 1 when component is small-sized, 0 otherwise.
53+
- `--is-medium` - Set to 1 when component is medium-sized, 0 otherwise
54+
- `--is-large` - Set to 1 when component is large-sized, 0 otherwise.
55+
- `--component-size` - Numeric value indicating current size (1=small, 2=medium, 3=large).
56+
57+
These variables are automatically managed by the theming system and change based on the component's size setting, controlled by `--ig-size`.
58+
59+
## Practical Usage Examples
60+
61+
### Global Spacing Control
62+
63+
To make all components more compact across your entire application:
64+
65+
```css
66+
:root {
67+
--ig-spacing: 0.8; /* 20% less spacing */
68+
}
69+
```
70+
71+
To increase spacing for better touch accessibility:
72+
73+
```css
74+
:root {
75+
--ig-spacing: 1.2; /* 20% more spacing */
76+
}
77+
```
78+
79+
### Component-Specific Spacing
80+
81+
To adjust spacing for a specific component type:
82+
83+
```css
84+
.my-grid {
85+
--ig-spacing: 0.5; /* More compact grid, 50% of the original spacing in all sizes */
86+
}
87+
```
88+
89+
### Directional Spacing Control
90+
91+
To reduce only horizontal spacing while keeping vertical spacing normal:
92+
93+
```css
94+
:root {
95+
--ig-spacing-inline: 0.7;
96+
--ig-spacing-block: 1.0;
97+
}
98+
```
99+
100+
### Size-Specific Spacing
101+
102+
To customize spacing for specific component sizes:
103+
104+
```css
105+
:root {
106+
--ig-spacing-small: 0.5; /* Very tight for small components */
107+
--ig-spacing-medium: 1.0; /* Normal for medium components */
108+
--ig-spacing-large: 1.5; /* Extra spacious for large components */
109+
}
110+
```
111+
112+
## How Spacing Multipliers Work
113+
114+
The spacing system uses multipliers to scale base values:
115+
116+
- Spacing values in components are multiplied by the active spacing variables
117+
- For example, if a component has `8px` base padding and you set `--ig-spacing: 1.5`, the actual padding becomes `12px`
118+
- Size-specific multipliers like `--ig-spacing-large` override the global `--ig-spacing` for large-sized components
119+
- Directional multipliers like `--ig-spacing-inline` allow you to scale horizontal and vertical spacing independently
120+
121+
This cascading approach ensures consistent spacing relationships while giving you fine-grained control through CSS custom properties alone.
122+
123+
## API References
124+
* [Utilities - Pad]({environment:sassApiUrl}/utilities#function-pad)
125+
* [Utilities - Pad Inline]({environment:sassApiUrl}/utilities#function-pad-inline)
126+
* [Utilities - Pad Block]({environment:sassApiUrl}/utilities#function-pad-block)
127+
128+
### Sizing Functions and Mixins
129+
* [Themes - Sizable Mixin]({environment:sassApiUrl}/themes#mixin-sizable)
130+
* [Themes - Sizable Function]({environment:sassApiUrl}/themes#function-sizable)
131+
132+
## Additional Resources
133+
<div class="divider--half"></div>
134+
135+
Our community is active and always welcoming to new ideas.
136+
137+
* [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular)
138+
* [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular)

‎en/components/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -900,6 +900,9 @@
900900
new: false
901901
- name: Size
902902
href: display-density.md
903+
- name: Spacing
904+
href: themes/spacing.md
905+
new: true
903906
- name: Sass
904907
new: false
905908
items:

0 commit comments

Comments
 (0)