diff --git a/docs/angular/package.json b/docs/angular/package.json index ab3ca766cf..02e3213384 100644 --- a/docs/angular/package.json +++ b/docs/angular/package.json @@ -37,7 +37,7 @@ "dependencies": { "astro": "^6.1.6", "docs-template": "file:../../", - "igniteui-astro-components": "0.0.27", + "igniteui-astro-components": "0.0.29", "sharp": "^0.34.2" }, "devDependencies": { diff --git a/docs/angular/src/content/en/components/button-group.mdx b/docs/angular/src/content/en/components/button-group.mdx deleted file mode 100644 index 10e8c3eea4..0000000000 --- a/docs/angular/src/content/en/components/button-group.mdx +++ /dev/null @@ -1,369 +0,0 @@ ---- -title: Angular Button Group Component – Ignite UI for Angular | Infragistics | MIT license -description: Provides button group functionality to developers and also allows horizontal/vertical alignment, single/multiple selection with toggling. -keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Controls, Native Angular Components Library, Angular Button Group components, Angular Button Group controls, Angular Buttons components, Angular Buttons controls -license: MIT -llms: - description: "Angular Button Group component is used to organize buttons into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling." ---- - -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; -import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; -import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; - -# Angular Button Group Component Overview - -
-Angular Button Group component is used to organize buttons into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling. -
- -## Angular Button Group Example - - - -
- -## Getting Started with Ignite UI for Angular Button Group - -To get started with the Ignite UI for Angular Button Group component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: - -```cmd -ng add igniteui-angular -``` - -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. - -The next step is to import the `IgxButtonGroupModule` in your **app.module.ts** file. - -```typescript -// app.module.ts - -... -import { IgxButtonGroupModule } from 'igniteui-angular/button-group'; -// import { IgxButtonGroupModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxButtonGroupModule], - ... -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxButtonGroupComponent` as a standalone dependency, or use the [`IGX_BUTTON_GROUP_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/button-group/src/button-group/public_api.ts) token to import the component and all of its supporting components and directives. - -```typescript -// home.component.ts - -... -import { IGX_BUTTON_GROUP_DIRECTIVES } from 'igniteui-angular/button-group'; -import { IgxIconComponent } from 'igniteui-angular/icon'; -// import { IGX_BUTTON_GROUP_DIRECTIVES, IgxIconComponent } from '@infragistics/igniteui-angular'; for licensed package - -@Component({ - selector: 'app-home', - template: ` - - - - - - - `, - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IGX_BUTTON_GROUP_DIRECTIVES, IgxIconComponent] - /* or imports: [IgxButtonGroupComponent, IgxButtonDirective, IgxIconComponent] */ -}) -export class HomeComponent {} -``` - - - -This component uses Material Icons. Add the following link to your `index.html`: `` - - -Now that you have the Ignite UI for Angular Button Group module or directives imported, you can start with a basic configuration of the `igx-buttongroup` and its buttons. - -## Using for Angular Button Group Component - -### Add Button Group - -Use the selector to wrap your buttons and display them into a button group. If you want a button to be selected by default, use the `selected` property: - -```html -{/* sample.component.html */} - - - - - - -``` - -## Examples - -### Alignment - -Use the input property to set the orientation of the buttons in the button group. - -```typescript -//sample.component.ts -import { ButtonGroupAlignment } from 'igniteui-angular/button-group'; -// import { ButtonGroupAlignment } from '@infragistics/igniteui-angular'; for licensed package - -... -public alignment = ButtonGroupAlignment.vertical; -... -``` - -```html -{/* sample.component.html */} - - - - - - -``` - - - -
- -### Selection - -In order to configure the `igx-buttongroup` selection, you could use its property. This property accepts the following three modes: - -- **single** - default selection mode of the button group. A single button can be selected/deselected by the user. -- **singleRequired** - mimics a radio group behavior. Only one button can be selected and once initial selection is made, deselection is not possible through user interaction. -- **multi** - multiple buttons in the group can be selected and deselected. - -The sample below demonstrates the exposed `igx-buttongroup` selection modes: - - - -### Size - -The `--ig-size` CSS custom property can be used to control the size of the button group. - -```scss -/* sample.component.scss */ -igx-buttongroup { - --ig-size: var(--ig-size-small); -} -``` - -```html -{/* sample.component.html */} - -``` - - - -### Custom toggle buttons - -Use the input property to set an array of customized buttons in the button group. - -```typescript -// sample.component.ts - -interface IButton { - ripple?: string; - label?: string; - disabled?: boolean; - togglable?: boolean; - selected?: boolean; - color?: string; - icon?: string; -} - -class ToggleButton { - private ripple: string; - private label: string; - private disabled: boolean; - private togglable: boolean; - private selected: boolean; - private color: string; - private icon: string; - - constructor(obj?: IButton) { - this.ripple = obj.ripple || 'gray'; - this.label = obj.label; - this.selected = obj.selected || false; - this.togglable = obj.togglable || true; - this.disabled = obj.disabled || false; - this.color = obj.color; - this.icon = obj.icon; - } -} -... -public bordersButtons: ToggleButton[]; - -public ngOnInit() { - this.bordersButtons = [ - new ToggleButton({ - icon: 'border_top', - selected: true - }), - new ToggleButton({ - icon: 'border_right', - selected: false - }), - new ToggleButton({ - icon: 'border_bottom', - selected: false - }), - new ToggleButton({ - icon: 'border_left', - selected: false - }) - ]; -} -... -``` - -```html -{/* sample.component.html */} - -``` - - - -## Styling - -### Button Group Theme Property Map - -When you set a value for the `$item-background` property, all related dependent properties listed in the table below are automatically updated to maintain visual consistency. The table shows which properties are affected when you customize the primary property. - -| Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$item-background** | $item-hover-background | The hover background color for items. | -| | $item-selected-background | The selected item background color. | -| | $item-focused-background | The focused item background color. | -| | $disabled-background-color | The disabled item background color. | -| | $item-border-color | The border color for items. | -| | $item-text-color | The text color for items. | -| | $idle-shadow-color | The idle shadow color for items. | -| **$item-hover-background** | $item-selected-hover-background | The selected item hover background color. | -| | $item-focused-hover-background | The focused hover background color. | -| | $item-hover-text-color | The text color for hovered items. | -| | $item-hover-icon-color | The icon color for hovered items. | -| **$item-selected-background** | $item-selected-focus-background | The selected item focus background color. | -| | $disabled-selected-background | The disabled selected background color. | -| | $item-selected-text-color | The text color for selected items. | -| | $item-selected-icon-color | The icon color for selected items. | -| | $item-selected-hover-text-color | The text color for selected hover items. | -| | $item-selected-hover-icon-color | The icon color for selected hover items. | -| **$item-border-color** | $item-hover-border-color | The border color for hovered items. | -| | $item-focused-border-color | The border color for focused items. | -| | $item-selected-border-color | The border color for selected items. | -| | $item-selected-hover-border-color | The border color for selected hover items. | -| | $item-disabled-border | The border color for disabled items. | -| | $disabled-selected-border-color | The border color for disabled selected items. | - -To get started with styling the button group, we need to import the `index` file, where all the theme functions and component mixins live: - -```scss -@use "igniteui-angular/theming" as *; - -// IMPORTANT: Prior to Ignite UI for Angular version 13 use: -// @import '~igniteui-angular/lib/core/styles/themes/index'; -``` - -Following the simplest approach, we create a new theme that extends the and specifying just the `$item-background`. Based on this value, the theme will automatically compute appropriate state colors, contrast foregrounds, and borders for the button group. Of course, you're still free to override any of the theme parameters with custom values if needed. - -```scss -$custom-button-group: button-group-theme( - $item-background: #57a5cd, -); -``` - -As seen, the `button-group-theme` exposes some useful parameters for basic styling of its items. If you want to drill deeper and change some button specific parameters, you can create a new theme that extends the `button-theme` and scope it under the respective button group class. - -The last step is to include the component's theme. - -```scss -:host { - @include tokens($custom-button-group); -} -``` - -### Demo - - - -### Styling with Tailwind - -You can style the `button-group` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. - -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: - -```scss -@import "tailwindcss"; -... -@use 'igniteui-theming/tailwind/utilities/material.css'; -``` - -The utility file includes both `light` and `dark` theme variants. - -- Use `light-*` classes for the light theme. -- Use `dark-*` classes for the dark theme. -- Append the component name after the prefix, e.g., `light-button-group`, `dark-button-group`. - -Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). - -You can find the full list of properties in the . The syntax is as follows: - -```html - -... - -``` - - -The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. - - -At the end your button group should look like this: - - - -## API References -
-- -- -- -- -## Theming Dependencies - -- -- -- - -## Additional Resources - -
- -Our community is active and always welcoming to new ideas. - -- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/list.mdx b/docs/angular/src/content/en/components/list.mdx index c8d30218f8..d4eaaadee0 100644 --- a/docs/angular/src/content/en/components/list.mdx +++ b/docs/angular/src/content/en/components/list.mdx @@ -300,7 +300,7 @@ toggleFavorite(item: IgxListItem) { } ``` -Let's also allow the user to choose the size of the list by using the `--ig-size` CSS custom property. We will do this by importing the `IgxButtonGroupModule` and using the [**IgxButtonGroup**](/button-group) to display all size values. This way whenever one gets selected, we will update the **size** of the list. +Let's also allow the user to choose the size of the list by using the `--ig-size` CSS custom property. We will do this by importing the `IgxButtonGroupModule` and using the `IgxButtonGroup` to display all size values. This way whenever one gets selected, we will update the **size** of the list. ```typescript // app.module.ts diff --git a/docs/angular/src/content/en/components/themes/roundness.mdx b/docs/angular/src/content/en/components/themes/roundness.mdx index b0ef36f9cc..e55e85a472 100644 --- a/docs/angular/src/content/en/components/themes/roundness.mdx +++ b/docs/angular/src/content/en/components/themes/roundness.mdx @@ -20,7 +20,7 @@ Many Ignite UI components have predefined minimum and maximum border-radius valu When you set `--ig-radius-factor` to 0, the component uses its minimum border-radius and will appear more block-like with sharp corners. When set to 1, the component uses its maximum predefined border-radius and will appear rounded. Here is a list of the components that have predefined minimum and maximum border-radius values and can be modified using the `--ig-radius-factor` variable:
-• [Action Strip](/action-strip) • [Button](/button) • [Button Group](/button-group) • [Calendar](/calendar) • [Card](/card) • [Carousel](/carousel) • [Checkbox](/checkbox) • [Chip](/chip) • [Combo](/combo) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/radio-button) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](/switch) • [Toast](/toast) +• [Action Strip](/action-strip) • [Button](/button) • [Calendar](/calendar) • [Card](/card) • [Carousel](/carousel) • [Checkbox](/checkbox) • [Chip](/chip) • [Combo](/combo) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/radio-button) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](/switch) • [Toast](/toast) ## Usage diff --git a/docs/angular/src/content/en/images/anatomy-content-light/button-group-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/button-group-lt-a.png new file mode 100644 index 0000000000..d4990ae354 Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/button-group-lt-a.png differ diff --git a/docs/angular/src/content/en/images/button-group/button-group-do-1.png b/docs/angular/src/content/en/images/button-group/button-group-do-1.png new file mode 100644 index 0000000000..4acaf050a9 Binary files /dev/null and b/docs/angular/src/content/en/images/button-group/button-group-do-1.png differ diff --git a/docs/angular/src/content/en/images/button-group/button-group-do-2.png b/docs/angular/src/content/en/images/button-group/button-group-do-2.png new file mode 100644 index 0000000000..d9c79b1461 Binary files /dev/null and b/docs/angular/src/content/en/images/button-group/button-group-do-2.png differ diff --git a/docs/angular/src/content/en/images/button-group/button-group-do-3.png b/docs/angular/src/content/en/images/button-group/button-group-do-3.png new file mode 100644 index 0000000000..2f016de185 Binary files /dev/null and b/docs/angular/src/content/en/images/button-group/button-group-do-3.png differ diff --git a/docs/angular/src/content/en/images/button-group/button-group-do-not-1.png b/docs/angular/src/content/en/images/button-group/button-group-do-not-1.png new file mode 100644 index 0000000000..4634972692 Binary files /dev/null and b/docs/angular/src/content/en/images/button-group/button-group-do-not-1.png differ diff --git a/docs/angular/src/content/en/images/button-group/button-group-do-not-2.png b/docs/angular/src/content/en/images/button-group/button-group-do-not-2.png new file mode 100644 index 0000000000..585f7ff91c Binary files /dev/null and b/docs/angular/src/content/en/images/button-group/button-group-do-not-2.png differ diff --git a/docs/angular/src/content/en/images/button-group/button-group-do-not-3.png b/docs/angular/src/content/en/images/button-group/button-group-do-not-3.png new file mode 100644 index 0000000000..68d4a04dc5 Binary files /dev/null and b/docs/angular/src/content/en/images/button-group/button-group-do-not-3.png differ diff --git a/docs/xplat/package.json b/docs/xplat/package.json index 4bac430430..0f2d48538e 100644 --- a/docs/xplat/package.json +++ b/docs/xplat/package.json @@ -67,7 +67,7 @@ "dependencies": { "astro": "^6.1.6", "docs-template": "file:../../", - "igniteui-astro-components": "0.0.27", + "igniteui-astro-components": "0.0.29", "sharp": "^0.34.2" }, "devDependencies": { diff --git a/docs/xplat/src/assets/images/button-group/button-group-do-1.png b/docs/xplat/src/assets/images/button-group/button-group-do-1.png new file mode 100644 index 0000000000..4acaf050a9 Binary files /dev/null and b/docs/xplat/src/assets/images/button-group/button-group-do-1.png differ diff --git a/docs/xplat/src/assets/images/button-group/button-group-do-2.png b/docs/xplat/src/assets/images/button-group/button-group-do-2.png new file mode 100644 index 0000000000..d9c79b1461 Binary files /dev/null and b/docs/xplat/src/assets/images/button-group/button-group-do-2.png differ diff --git a/docs/xplat/src/assets/images/button-group/button-group-do-3.png b/docs/xplat/src/assets/images/button-group/button-group-do-3.png new file mode 100644 index 0000000000..2f016de185 Binary files /dev/null and b/docs/xplat/src/assets/images/button-group/button-group-do-3.png differ diff --git a/docs/xplat/src/assets/images/button-group/button-group-do-not-1.png b/docs/xplat/src/assets/images/button-group/button-group-do-not-1.png new file mode 100644 index 0000000000..4634972692 Binary files /dev/null and b/docs/xplat/src/assets/images/button-group/button-group-do-not-1.png differ diff --git a/docs/xplat/src/assets/images/button-group/button-group-do-not-2.png b/docs/xplat/src/assets/images/button-group/button-group-do-not-2.png new file mode 100644 index 0000000000..585f7ff91c Binary files /dev/null and b/docs/xplat/src/assets/images/button-group/button-group-do-not-2.png differ diff --git a/docs/xplat/src/assets/images/button-group/button-group-do-not-3.png b/docs/xplat/src/assets/images/button-group/button-group-do-not-3.png new file mode 100644 index 0000000000..68d4a04dc5 Binary files /dev/null and b/docs/xplat/src/assets/images/button-group/button-group-do-not-3.png differ diff --git a/docs/xplat/src/content/en/components/inputs/button-group.mdx b/docs/xplat/src/content/en/components/inputs/button-group.mdx index a61151ce6a..e640f77799 100644 --- a/docs/xplat/src/content/en/components/inputs/button-group.mdx +++ b/docs/xplat/src/content/en/components/inputs/button-group.mdx @@ -1,40 +1,110 @@ --- -title: "{Platform} Button Group Component | {ProductName}" -description: Get started with the {Platform} Button Group Component - series of {Platform} Toggle Buttons, exposing features such as layout and selection. +title: "Button Group" +description: The {ProductName} Button Group component organizes related toggle buttons and supports horizontal or vertical alignment, single or multiple selection, and toggling. keywords: "{Platform}, UI controls, web widgets, UI widgets, {Platform} Button Group Components, Infragistics" mentionedTypes: ["ToggleButton", "ButtonGroup"] +relatedComponents: [ToggleButton] license: MIT +last_updated: "2026-07-28" llms: - description: "The {Platform} Button Group component is used to organize ToggleButton's into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling." + description: "The {ProductName} Button Group organizes related toggle buttons into a group with horizontal or vertical alignment, single or multiple selection, and toggling." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import buttonGroupAnatomy from '@xplat-images/anatomy-content-light/button-group-lt-a.png'; +import buttonGroupDo1 from '@xplat-images/button-group/button-group-do-1.png'; +import buttonGroupDo2 from '@xplat-images/button-group/button-group-do-2.png'; +import buttonGroupDo3 from '@xplat-images/button-group/button-group-do-3.png'; +import buttonGroupDoNot1 from '@xplat-images/button-group/button-group-do-not-1.png'; +import buttonGroupDoNot2 from '@xplat-images/button-group/button-group-do-not-2.png'; +import buttonGroupDoNot3 from '@xplat-images/button-group/button-group-do-not-3.png'; + +# Button Group Component +The {Platform} Button Group component is used to organize 's into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling. -# {Platform} Button Group Overview +## Live Demo -The {Platform} Button Group component is used to organize 's into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling. + + + + + -## {Platform} Button Example + + -## Usage +## Anatomy +The {Platform} Button Group organizes related Toggle Buttons into a single group with a shared container and individual button items. - + + + + +1. Container: Wraps the button's contents.
+2. Icon: Adds context to the button. Could be left, right, left and right or only icon.
+3. Label: The textual content that describes the button’s action to the user. + +The {Platform} Button Group contains Toggle Buttons, and each button can contain an icon and a label. + +```text +Button Group +└── Toggle Button + ├── Icon + └── Label +``` + +## Getting Started + + + +To use the {Platform} Button Group, follow the [{ProductName} Getting Started](/general/getting-started) topic for the basic project setup, then register the component for your target platform. + + + + +To use the {Platform} Button Group, follow the [{ProductName} Getting Started](../general-getting-started.mdx) topic for the basic project setup, then register the component for your target platform. + + + +### Prerequisites and Version Compatibility + +Use a supported version of the {ProductName} package for your target framework. Keep the framework package, the Button Group package, and the theme package on the same release version. + + -First, you need to install the {ProductName} by running the following command: +For Web Components using the **{PackageWebComponents}** package, install the package: ```cmd npm install {PackageWebComponents} ``` -You will then need to import the , its necessary CSS, and register its module, like so: +Then import the , its theme CSS, and register the component: ```ts import { defineComponents, IgcButtonGroupComponent } from "igniteui-webcomponents"; @@ -45,18 +115,15 @@ defineComponents(IgcButtonGroupComponent); - - - -First, you need to the install the corresponding {ProductName} npm package by running the following command: +For React using the **igniteui-react** package, install the package: ```cmd npm install igniteui-react ``` -You will then need to import the and its necessary CSS, like so: +Then import the Button Group wrapper and its theme CSS: ```tsx import { IgrButtonGroup } from 'igniteui-react'; @@ -65,12 +132,9 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; - - - -Before using the , you need to register it as follows: +For Blazor using the **IgniteUI.Blazor** package, register the Button Group module as follows: ```csharp // in Program.cs file @@ -78,7 +142,7 @@ Before using the , you need to register builder.Services.AddIgniteUIBlazor(typeof(IgbButtonGroupModule)); ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Then link the additional CSS file in the **wwwroot/index.html** file for a **Blazor WebAssembly** project or in the **Pages/_Host.cshtml** file for a **Blazor Server** project: ```razor @@ -86,12 +150,80 @@ You will also need to link an additional CSS file to apply the styling to the + -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.mdx) topic. +For Angular using the **igniteui-angular** package, install the package: -Now that you have the {ProductName} Button Group imported, you can start with a basic configuration of the and its buttons. +```cmd +ng add igniteui-angular +``` -Use the selector to wrap your s and display them into a button group. If you want a button to be selected by default, use the attribute: +Then import `IgxButtonGroupModule` in an NgModule application, or import `IGX_BUTTON_GROUP_DIRECTIVES` and the required standalone components in the component `imports` collection. + +```ts +import { IGX_BUTTON_GROUP_DIRECTIVES } from 'igniteui-angular/button-group'; +import { IgxIconComponent } from 'igniteui-angular/icon'; +``` + +For a complete introduction to Ignite UI for Angular, read the [**Getting Started**](/general/getting-started) topic. + + + +The simplest way to start using the is as follows: + + + +```html + +``` + + + + + +```tsx + +``` + + + + + +```razor + +``` + + + + + +```html + +``` + + + +## Usage + +Use the to wrap your components. To select a button by default, use the attribute: + + + +```html + + + + + +``` + + @@ -171,24 +303,75 @@ Use the selector to wrap your -## Examples - ### Alignment -Use the property to set the orientation of the buttons in the button group. + +The Button Group supports horizontal and vertical layouts. Use the property to set the orientation of the buttons in the group. + + + +For Angular, set the `alignment` input with the `ButtonGroupAlignment` enum: + +```ts +import { ButtonGroupAlignment } from 'igniteui-angular/button-group'; + +public alignment = ButtonGroupAlignment.vertical; +``` + +```html + + + + + + +``` + + + + + + + + +### Buttons Amount + +Use only the number of buttons needed for the related actions in the group. Keep the Button Group sized to its content so that the buttons do not contain unnecessary empty space. ### Selection -In order to configure the {ProductName} selection, you could use its property. This property accepts the following three modes: +In order to configure the {ProductName} selection, use its platform-specific selection property. For Angular, use . For React, Web Components, and Blazor, use . The available modes are: - **single** - default selection mode of the button group. A single button can be selected/deselected by the user. - **single-required** - mimics a radio group behavior. Only one button can be selected and once initial selection is made, deselection is not possible through user interaction. - **multiple** - multiple buttons in the group can be selected and deselected. The sample below demonstrates the exposed selection modes: + + +The Angular selection modes are `single`, `singleRequired`, and `multi`. + +Set the Angular `selectionMode` input to configure the selection behavior: + +```html + + + + + +``` + + + + + + + + + A could be marked as selected via its attribute or through the attribute: @@ -263,16 +446,311 @@ A could be marked as selected via its Setting attribute is mandatory for using the property of the . +### States + +The buttons in the group support their available interaction states, including idle, hover, focus, selected, and disabled states. Use the state behavior provided by the contained components. + +### Button Group Layout Template + +Each button can use text, an icon, or both. Keep the content style consistent across the group, and use the button content APIs to control the icon and label shown in each button. + + + +### Custom Toggle Buttons + + + +For Angular, use the `values` input to provide an array of customized buttons. Each item can define properties such as `label`, `icon`, `selected`, `disabled`, and `togglable`. + +Define the button values in the component class: + +```ts +interface IButton { + label?: string; + icon?: string; + disabled?: boolean; + togglable?: boolean; + selected?: boolean; + color?: string; +} + +public bordersButtons: IButton[] = [ + { icon: 'border_top', selected: true }, + { icon: 'border_right' }, + { icon: 'border_bottom' }, + { icon: 'border_left' } +]; +``` + +```html + +``` + +See the Angular Button Group sample for the complete `values` model and configuration. + + + + + + + +For Web Components, use individual Toggle Buttons to create a custom Button Group. Each button can define its own value, icon, label, selected state, and disabled state. + +Register the Button Group and Toggle Button components: + +```ts +import { defineComponents, IgcButtonGroupComponent, IgcToggleButtonComponent, IgcIconComponent } from 'igniteui-webcomponents'; + +defineComponents(IgcButtonGroupComponent, IgcToggleButtonComponent, IgcIconComponent); +``` + +Then define the custom buttons in markup: + +```html + + + + + + + + + + + +``` + + + + + + + +For React, use individual Toggle Buttons to create a custom Button Group. Each button can define its own value, icon, label, selected state, and disabled state. + +Import the Button Group, Toggle Button, and Icon components: + +```tsx +import { IgrButtonGroup, IgrToggleButton, IgrIcon } from 'igniteui-react'; +``` + +Then define the custom buttons in JSX: + +```tsx + + + + + + + + + + + +``` + + + + + + + +For Blazor, use individual Toggle Buttons to create a custom Button Group. Each button can define its own value, icon, label, selected state, and disabled state. + +Register the Button Group module in `Program.cs`: + +```csharp +builder.Services.AddIgniteUIBlazor(typeof(IgbButtonGroupModule)); +``` + +Then define the custom buttons in Razor markup: + +```razor + + + + + + + + + + + +``` + + + + + ### Size The `--ig-size` CSS custom property can be used to control the size of the button group. + + +```scss +igx-buttongroup { + --ig-size: var(--ig-size-small); +} +``` + +```html + +``` + + + + + + + + + +### Do/Don't + +**When to use:** Use a Button Group to organize related toggle actions where users may select one or more options. + +**When not to use:** Do not use a Button Group for unrelated actions or for a single toggle action; use a standalone instead. + +
+ + + + + + + + + + + + + + + + + + + + + +
DoDon't
Button Group do example 1Button Group don't example 1
Button Group do example 2Button Group don't example 2
Button Group do example 3Button Group don't example 3
+
+ +## Properties + +The Button Group properties are generated from the component API reference. + +The property rows are injected from the typed API source during the documentation build. + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `ButtonGroupAlignment` | `horizontal` | Sets the orientation of the buttons in the group. | +| | `ButtonGroupSelection` | `single` | Sets the selection mode for the buttons in the group. | +| | `string[]` | `[]` | Gets or sets the values of the selected buttons. Each Toggle Button must have a unique `value`. | ## Styling -The component exposes `group` CSS part that allows us to style the button group container. -Also, the s provide `toggle` CSS part that could be used to style the button element. + + +The Angular Button Group theme exposes Sass parameters for the group items and their interaction states. Changing a primary theme property updates its related state properties to keep the component visually consistent. + +### Button Group Theme Property Map + +| Primary property | Dependent property | Description | +| --- | --- | --- | +| `$item-background` | `$item-hover-background` | Hover background for items. | +| | `$item-selected-background` | Selected item background. | +| | `$item-focused-background` | Focused item background. | +| | `$disabled-background-color` | Disabled item background. | +| | `$item-border-color` | Default item border color. | +| | `$item-text-color` | Default item text color. | +| | `$idle-shadow-color` | Idle item shadow color. | +| `$item-hover-background` | `$item-selected-hover-background` | Selected item hover background. | +| | `$item-focused-hover-background` | Focused hover background. | +| | `$item-hover-text-color` | Hovered item text color. | +| | `$item-hover-icon-color` | Hovered item icon color. | +| `$item-selected-background` | `$item-selected-focus-background` | Selected item focus background. | +| | `$disabled-selected-background` | Disabled selected background. | +| | `$item-selected-text-color` | Selected item text color. | +| | `$item-selected-icon-color` | Selected item icon color. | +| | `$item-selected-hover-text-color` | Selected hovered item text color. | +| | `$item-selected-hover-icon-color` | Selected hovered item icon color. | +| `$item-border-color` | `$item-hover-border-color` | Hovered item border color. | +| | `$item-focused-border-color` | Focused item border color. | +| | `$item-selected-border-color` | Selected item border color. | +| | `$item-selected-hover-border-color` | Selected hovered item border color. | +| | `$item-disabled-border` | Disabled item border color. | +| | `$disabled-selected-border-color` | Disabled selected border color. | + +Import the Angular theming functions before creating a custom Button Group theme: + +```scss +@use "igniteui-angular/theming" as *; +``` + +Create a theme with `button-group-theme` and include it in the component scope: + +```scss +$custom-button-group: button-group-theme( + $item-background: #57a5cd, +); + +:host { + @include tokens($custom-button-group); +} +``` + + + +### Styling with Tailwind + +You can style the Angular Button Group with the Ignite UI Tailwind utility classes. First, [set up Tailwind](/themes/misc/tailwind-classes), then import the utility file in the global stylesheet: + +```scss +@import "tailwindcss"; +@use 'igniteui-theming/tailwind/utilities/material.css'; +``` + +Use `light-button-group` or `dark-button-group` for the corresponding theme and override generated CSS variables with arbitrary properties: + +```html + + +``` + +The exclamation mark (`!`) makes the utility class important so it takes precedence over the component theme. + + + + + + + +The {Platform} Button Group uses CSS parts to style the group container and the individual Toggle Buttons. Use the `group` part on the Button Group and the `toggle` part on each Toggle Button to customize their appearance. + + + +### CSS Parts + +Use the following CSS parts to target the Button Group and its contained Toggle Buttons: + +| Part | Component | What it styles | +| --- | --- | --- | +| `group` | | The Button Group container. | +| `toggle` | | An individual Toggle Button. | + +### Custom Styling + +The following example changes the group background and padding, and changes the text color of the contained Toggle Buttons: + +| Selector | Declaration | Effect | +| --- | --- | --- | +| `igc-button-group::part(group)` | `background-color`, `padding` | Changes the Button Group container background and spacing. | +| `igc-toggle-button::part(toggle)` | `color` | Changes the text color of an individual Toggle Button. | ```css igc-button-group::part(group) { @@ -285,15 +763,87 @@ igc-toggle-button::part(toggle) { } ``` - + + +## Accessibility + +The Button Group groups related Toggle Buttons while preserving the interaction and accessible state of each button. Provide meaningful content for every button and choose a selection mode that matches the intended interaction. + +### Keyboard Interaction + +The {Platform} Button Group follows the keyboard behavior of its Toggle Buttons. Use the keyboard interaction provided by the contained buttons and verify the focus order and selection behavior for the configured selection mode. + +| Interaction | Expected behavior | +| --- | --- | +| Keyboard focus | The user can reach the contained Toggle Buttons according to their focus behavior. | +| Toggle Button interaction | The focused button changes its selected state according to the configured selection mode. | + +### Screen Readers / ARIA + +Use clear labels for every {Platform} Toggle Button so assistive technology users can identify each option and its selected state. When an icon does not provide an accessible name, provide an appropriate text label or accessible name for the button. + +### Accessibility Compliance + +Verify the rendered {Platform} Button Group against the accessibility requirements of the application. Check the button names, focus order, selected state announcements, and behavior for the configured selection mode in the target framework. + +## Troubleshooting + +The {Platform} Button Group troubleshooting guidance follows a problem, cause, and fix format for common selection issues. + +### Why does selectedItems not select a button? + +Ensure every Toggle Button has a unique `value` attribute. The `selectedItems` property depends on those values. + +### Known Limitations + +The {Platform} Button Group coordinates Toggle Buttons but does not replace their individual labels or accessible names. +- Selection behavior depends on the configured `selection` mode. +- The `selectedItems` property depends on unique `value` attributes on the contained Toggle Buttons. +- The Button Group does not provide labels or icons for its buttons; define the content of each Toggle Button separately. ## API References + +The {Platform} Button Group API reference provides the complete API surface for the component and its related Toggle Button functionality. + + +## Dependencies + +The {Platform} Button Group requires the platform package and its theme stylesheet. The examples also use Toggle Button, Icon, and Ripple components. + ## Additional Resources +Use the following {Platform} resources for API details and project support: + - [{ProductName} **Forums**]({ForumsLink}) - [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + +The {Platform} Button Group is built from selectable Toggle Buttons. Use the following related component when you need an individual toggle action instead of a group: + +- + +## FAQ + +These frequently asked questions cover common {Platform} Button Group selection, content, and setup scenarios. + + + + +The Button Group supports `single`, `single-required`, and `multiple` selection modes. Use the `selection` property to choose the mode that matches the interaction you need. + + + +Assign a unique `value` to every and set the corresponding values through the Button Group's `selectedItems` property. + + + +Yes. Add an icon to each and keep the button content consistent across the group. + + + diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index 17c916bd26..59a1f30100 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2448,9 +2448,6 @@ "href": "inputs/button.mdx" }, { - "exclude": [ - "Angular" - ], "name": "Button Group", "href": "inputs/button-group.mdx" }, diff --git a/package-lock.json b/package-lock.json index a871c5cf87..b6b224dba4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,7 +14,7 @@ "dependencies": { "astro-seo-schema": "^6.0.0", "gray-matter": "^4.0.3", - "igniteui-astro-components": "0.0.27", + "igniteui-astro-components": "0.0.29", "igniteui-theming": "^25.0.2", "igniteui-webcomponents": "^7.2.4", "js-yaml": "^4.1.1", @@ -48,7 +48,7 @@ "dependencies": { "astro": "^6.1.6", "docs-template": "file:../../", - "igniteui-astro-components": "0.0.27", + "igniteui-astro-components": "0.0.29", "sharp": "^0.34.2" }, "devDependencies": { @@ -83,7 +83,7 @@ "dependencies": { "astro": "^6.1.6", "docs-template": "file:../../", - "igniteui-astro-components": "0.0.27", + "igniteui-astro-components": "0.0.29", "sharp": "^0.34.2" }, "devDependencies": { @@ -5666,9 +5666,9 @@ } }, "node_modules/igniteui-astro-components": { - "version": "0.0.27", - "resolved": "https://registry.npmjs.org/igniteui-astro-components/-/igniteui-astro-components-0.0.27.tgz", - "integrity": "sha512-IqwYm7CcBYISnuqd8uzllbjCgIt6pdhmO1+aiPUfiBncSQfM5xIanX2vGvRSz3dhxOSkBD0VZmLBvQ0HMT2+uQ==", + "version": "0.0.29", + "resolved": "https://registry.npmjs.org/igniteui-astro-components/-/igniteui-astro-components-0.0.29.tgz", + "integrity": "sha512-Z2t9/hdq5cVC/C+UmW53shMtDX0fbgCSp3uce1HfRO+/Zlgi2sfeTfmZEzDBgZcmK9eXWDs0UizSmE8wkXfqCw==", "license": "MIT", "workspaces": [ "playground" diff --git a/package.json b/package.json index b9310ccea4..05bd752e7f 100644 --- a/package.json +++ b/package.json @@ -149,7 +149,7 @@ "dependencies": { "astro-seo-schema": "^6.0.0", "gray-matter": "^4.0.3", - "igniteui-astro-components": "0.0.27", + "igniteui-astro-components": "0.0.29", "igniteui-theming": "^25.0.2", "igniteui-webcomponents": "^7.2.4", "js-yaml": "^4.1.1",