diff --git a/docs/angular/src/content/en/components/general/cli/component-templates.mdx b/docs/angular/src/content/en/components/general/cli/component-templates.mdx index d073cce00c..9c11236aa2 100644 --- a/docs/angular/src/content/en/components/general/cli/component-templates.mdx +++ b/docs/angular/src/content/en/components/general/cli/component-templates.mdx @@ -42,7 +42,7 @@ These templates generate components into an existing Angular workspace only. The | Layouts | | | | dock-manager | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c dock-manager newDockManager
Ignite UI CLI:
ig add dock-manager newDockManager
Basic IgcDockManager.
| [IgcDockManager](../../dock-manager.mdx) with nine content slots. | | carousel | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c carousel newCarousel
Ignite UI CLI:
ig add carousel newCarousel
Basic IgxCarousel.
| [IgxCarousel](../../layouts/carousel.mdx) cycling through a series of images. | -| tabs | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c tabs newTabs
Ignite UI CLI:
ig add tabs newTabs
Basic IgxTabs.
| [IgxTabs](../../tabs.mdx) component that includes three customized tab-groups. | +| tabs | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c tabs newTabs
Ignite UI CLI:
ig add tabs newTabs
Basic IgxTabs.
| [IgxTabs](../../layouts/tabs.mdx) component that includes three customized tab-groups. | | bottom-nav | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c bottom-nav newBottomNav
Ignite UI CLI:
ig add bottom-nav newBottomNav
Three item bottom-nav template.
| Three item bottom [navbar](../../navbar.mdx) template. | | accordion | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c accordion newAccordion
Ignite UI CLI:
ig add accordion newAccordion
Basic IgxAccordion sample.
| [IgxAccordion](../../layouts/accordion.mdx) with multiple collapsible panels in a single container. | | stepper | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c stepper newStepper
Ignite UI CLI:
ig add stepper newStepper
Basic IgxStepper sample.
| [IgxStepper](../../stepper.mdx) visualizing content as a process with successive steps. | diff --git a/docs/angular/src/content/en/components/tabs.mdx b/docs/angular/src/content/en/components/tabs.mdx deleted file mode 100644 index 22cbc9fd6e..0000000000 --- a/docs/angular/src/content/en/components/tabs.mdx +++ /dev/null @@ -1,613 +0,0 @@ ---- -title: Angular Tabs Component | Ignite UI for Angular | MIT license -description: The Ignite UI for Angular Tabs component places tabs at the top and allows for scrolling when there are multiple tab items on the screen. Try it now. -keywords: Angular Tabs component, Angular Tabs control, Angular Tabs, Angular Tabbar Component, Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Components, Angular UI Components, Native Angular Components Library -license: MIT -llms: - description: "Ignite UI for Angular Tabs is a full-featured user interface component that has the primary purpose to organize and group related content in a single tabbed view, thus saving space and making content more comprehensible." ---- - -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 Tabs Component Overview - -Ignite UI for Angular Tabs is a full-featured user interface component that has the primary purpose to organize and group related content in a single tabbed view, thus saving space and making content more comprehensible. It packs different features like animations, templating, customization options, and others. - -Tabs in Angular are extremely useful when you’re building a web page with plenty of content that must be fitted into categories and displayed in a concise and space-efficient way. - -
- -The component in Ignite UI for Angular is used to organize or switch between similar data sets. It functions as a wrapper for which respectively represent the container for the data and the tab header. The Angular Tabs Component places tabs at the top and allows scrolling when there are multiple tab items on the screen. - -
- -## Angular Tabs Example - -This is a basic example of Angular Nested Tabs where we have one tab within another where only one view can be seen at the time. Using nested tabs in Angular, we can display information in a better, structured way. - - - -
- -## Getting Started with Ignite UI for Angular Tabs - -To get started with the Ignite UI for Angular Tabs 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.mdx) topic. - -The next step is to import the `IgxTabsModule` in your **app.module.ts** file. - -```typescript -// app.module.ts - -... -import { IgxTabsModule } from 'igniteui-angular/tabs'; -// import { IgxTabsModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxTabsModule], - ... -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxTabsComponent` as a standalone dependency, or use the [`IGX_TABS_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/tabs/src/tabs/tabs/public_api.ts) token to import the component and all of its supporting components and directives. - -```typescript -// home.component.ts - -import { IGX_TABS_DIRECTIVES } from 'igniteui-angular/tabs'; -// import { IGX_TABS_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package - -@Component({ - selector: 'app-home', - template: ` - - - - Tab 1 - - - This is Tab 1 content. - - - - - Tab 2 - - - This is Tab 2 content. - - - - `, - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IGX_TABS_DIRECTIVES] - /* or imports: [IgxTabsComponent, IgxTabItemComponent, IgxTabHeaderComponent, IgxTabContentComponent, IgxTabHeaderLabelDirective] */ -}) -export class HomeComponent {} -``` - -Now that you have the Ignite UI for Angular Tabs module or directives imported, you can start using the `igx-tabs` component. - -## Using the Angular Tabs - -We set the Angular Tabs header by providing content to `igx-tab-header`. To set the tab's name we simply add a span with `igxTabHeaderLabel` directive. Any content that will appear as a tab item's content should be added between `igx-tab-content` tags. - -```html - - - - Tab 1 - - - This is Tab 1 content. - - - - - Tab 2 - - - This is Tab 2 content. - - - - - Tab 3 - - - This is Tab 3 content. - - - - - Tab 4 - - - This is Tab 4 content. - - - - - Tab 5 - - - This is Tab 5 content. - - - -``` - -If the sample is configured properly, the final result should look like that: - - - - - -## Angular Tabs Alignment - -`IgxTabs` input property controls how tabs are positioned and arranged. It accepts four different values - start, center, end and justify. - -- **Start** (default): the width of the tab header depends on the content (label, icon, both) and all tabs have equal padding. First tab is aligned to the tabs container left side. -- **Center**: the width of the tab header depends on the content and occupies the tabs container center. If the space is not enough to fit all items, scroll buttons are displayed. -- **End**: the width of the tab header depends on the content and all tabs have equal padding. Last tab is aligned to the tabs container right side. -- **Justify**: all tab headers are equal in width and fully fit the tabs container. If the space is not enough to fit all items, scroll buttons are displayed. - -Sample below demonstrates how tabs get aligned when switching between `tabAlignment` property values. - - - - - -## Customizing Angular Tabs - -Let's modify the tabs and make them more appealing by including icons using the `igxTabHeaderIcon` directive. The `igx-tabs` component is compatible with the Material Design -[**Icons**](https://material.io/icons/) so it will be very easy to adopt them in your application. - -If you haven't used the `igx-icon` in your application so far, please make sure to import the `IgxIconModule` in the **app.module.ts** before proceeding. - - -First, add the Material Icons in your 'styles.scss' file in the main application folder. Next, add `igx-icon` with `igxTabHeaderIcon` directive set, as a child of `igx-tab-header`. - -```css -// styles.scss - -... -@import url('https://fonts.googleapis.com/icon?family=Material+Icons'); -... -``` - -```html - - - - library_music - Albums - - - Albums - - - - - favorite - Favorite - - - Favorite - - - - - info - Details - - - Details - - - - -``` - -If the sample is configured properly, the tabs should look like the following example: - - - -
- -If setting the labels and icons is not enough, you can also provide your own custom content directly between `igx-tab-header` tags. - -```html - - - - {/* your custom tab content goes here */} -
- - -
- - -

IgniteUI Rocks!

- - - -``` - -You can also add you own custom tab header's prefix and suffix simply by using `igxPrefix` and `igxSuffix` directives. The sample below demonstrates how to add a tab with custom header content and prefix/suffix. - - - -
- -## Integration With Router Outlet Container - -Although the `igx-tabs` component is meant to be used as a list of tabs with content specified for each tab item, there might be cases in which you need to define tab items where the content is separate from the tab content. - -When defining tab items you have the ability to apply directives to them. For example, you may use this functionality to achieve navigation between views using the Angular Router. The following example will demonstrate how to configure the `igx-tabs` component to switch between three components in a single router-outlet. - -To start we need a component to hold our `igx-tabs` component and three view components with some content for demonstration purposes. For simplicity, the view components have very short templates. - -```typescript -import { Component } from '@angular/core'; - -@Component({ - selector: 'app-tabs-routing', - styleUrls: ['tabs-routing.component.scss'], - templateUrl: 'tabs-routing.component.html' -}) -export class TabsRoutingComponent { } - -@Component({ - template: '

Tab 1 Content

' -}) -export class TabsRoutingView1Component { } - -@Component({ - template: '

Tab 2 Content

' -}) -export class TabsRoutingView2Component { } - -@Component({ - template: '

Tab 3 Content

' -}) -export class TabsRoutingView3Component { } -``` - -Next, we create the appropriate navigation mappings in the `app-routing.module.ts` file: - -```typescript -import { RouterModule, Routes } from '@angular/router'; - -import { - TabsRoutingComponent, - TabsRoutingView1Component, - TabsRoutingView2Component, - TabsRoutingView3Component -} from './tabs-routing.component'; - -... - -const routes: Routes = [ - { - path: '', - pathMatch: 'full', - redirectTo: '/tabs-routing' - }, - { - path: 'tabs-routing', - component: TabsRoutingComponent, - children: [ - { path: 'view1', component: TabsRoutingView1Component }, - { path: 'view2', component: TabsRoutingView2Component }, - { path: 'view3', component: TabsRoutingView3Component }, - ] - } -]; - -@NgModule({ - exports: [RouterModule], - imports: [RouterModule.forRoot(appRoutes)] -}) -export class AppRoutingModule { } -``` - -Now that we have all navigation routes set up, we need to declare the `igx-tabs` component and configure it for routing. Make sure to add a router-outlet for rendering the view components. - -```html -{/* tabs-routing.component.html */} - - - - - Tab 1 - - - - - Tab 2 - - - - - Tab 3 - - - - - -``` - -The above code creates an `igx-tabs` component with three tab items. Each tab item's header has the `RouterLink` directive applied, which is used to specify the routing link used for the navigation. If any of the links becomes active, the corresponding tab item will have its property set because of the binding to the `RouterLinkActive` directive's `isActive` property. This way the selected tab item will always be synchronized with the current url path. - - - - -Please note that the routerLink directive is set to the `igx-tab-header`, not directly to the `igx-tab-item`. - - -## Styles - -### Tabs Theme Property Map - -When you modify a primary property, all related dependent properties are automatically updated to reflect the change: - -
- - - - - - - - - - -
- -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$item-background** | $item-active-background | The color used for the active/focused tab background. | -| | $item-text-color | The color used for the tab text color. | -| | $item-icon-color | The color used for the tab icon. | -| | $item-hover-background | The background used for the tabs on hover. | -| | $indicator-color | The color used for the active tab indicator. | -| | $button-background | The color used for the button background. | -| | $button-hover-background | The color used for the button background on hover. | -|**$item-active-background** | $item-active-icon-color | The color used for the active tab icon. | -| | $item-active-color | The color used for the active tabs text. | -| | $tab-ripple-color | The color used for the button background. | -| **$item-text-color** | $item-hover-color | The text color used for the tabs on hover if no `$item-hover-background` is provided | -| | $item-icon-color | The color used for the tab icon if no `$item-background` is provided | -| | $item-active-color | The color used for the active tabs text if no `$item-active-background` is provided | -| | $indicator-color | The color used for the active tab indicator if no `$item-background` is provided | -|**$item-icon-color** | $item-hover-icon-color | The color used for the tab icon on hover. | -| | $item-active-icon-color | The color used for the active tab icon. | -| | $indicator-color | The color used for the active tab indicator. | -| **$button-background** | $button-hover-background | The color used for the button background on hover. | -| | $button-color | The color used for the button icon/text color. | -| **$button-color** | $button-disabled-color | The color used for the disabled button icon/text. | -| | $button-ripple-color | The color used for the button background on hover. | -| **$button-hover-background** | $button-hover-color | The color used for the button icon/text color on hover. | - -
-
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$item-background** | $item-active-background | The color used for the active/focused tab background. | -| | $item-text-color | The color used for the tab text color. | -| | $item-icon-color | The color used for the tab icon. | -| | $item-hover-background | The background used for the tabs on hover. | -| | $indicator-color | The color used for the active tab indicator. | -| | $button-background | The color used for the button background. | -| | $button-hover-background | The color used for the button background on hover. | -|**$item-active-background** | $item-active-icon-color | The color used for the active tab icon. | -| | $item-active-color | The color used for the active tabs text. | -| | $tab-ripple-color | The ripple color for the tab interaction. | -| **$item-text-color** | $item-hover-color | The text color used for the tabs on hover if no `$item-hover-background` is provided | -| | $item-icon-color | The color used for the tab icon if no `$item-background` is provided | -| | $item-active-color | The color used for the active tabs text if no `$item-active-background` is provided | -| | $indicator-color | The color used for the active tab indicator if no `$item-background` is provided | -|**$item-icon-color** | $item-hover-icon-color | The color used for the tab icon on hover. | -| | $item-active-icon-color | The color used for the active tab icon. | -| | $indicator-color | The color used for the active tab indicator. | -| **$button-background** | $button-hover-background | The color used for the button background on hover. | -| | $button-color | The color used for the button icon/text color. | -| **$button-color** | $button-disabled-color | The color used for the disabled button icon/text. | -| | $button-ripple-color | The color used for the button background on hover. | -| **$button-hover-background** | $button-hover-color | The color used for the button icon/text color on hover. | - -
-
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$item-background** | $item-active-background | The color used for the active/focused tab background. | -| | $item-text-color | The color used for the tab text color. | -| | $item-icon-color | The color used for the tab icon. | -| | $item-hover-background | The background used for the tabs on hover. | -| | $indicator-color | The color used for the active tab indicator. | -| | $button-background | The color used for the button background. | -| | $button-hover-background | The color used for the button background on hover. | -| | $border-color | The border color of the tabs. | -| **$item-active-background** | $item-active-icon-color | The color used for the active tab icon. | -| | $item-active-color | The color used for the active tabs text. | -| | $tab-ripple-color | The color used for the button background. | -| **$item-text-color** | $item-hover-color | The text color used for the tabs on hover if no `$item-hover-background` is provided | -| | $item-icon-color | The color used for the tab icon if no `$item-background` is provided | -| | $button-color | The color used for the button icon/text color if no `$button-background` is provided (non-material) | -| **$item-icon-color** | $item-hover-icon-color | The color used for the tab icon on hover if no `$item-hover-background` is provided | -| | $item-text-color | The color used for the tab text color if no `$item-background` is provided | -| **$button-background** | $button-hover-background | The color used for the button background on hover. | -| | $button-color | The color used for the button icon/text color. | -| **$button-color** | $button-hover-color | The color used for the button icon/text color on hover if no `$button-background` is provided | -| | $button-disabled-color | The color used for the disabled button icon/text. | -| | $button-ripple-color | The color used for the button background on hover. | -| **$button-hover-background** | $button-hover-color | The color used for the button icon/text color on hover. | - -
-
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$item-background** | $item-active-background | The color used for the active/focused tab background. | -| | $item-text-color | The color used for the tab text color. | -| | $item-icon-color | The color used for the tab icon. | -| | $item-hover-background | The background used for the tabs on hover. | -| | $indicator-color | The color used for the active tab indicator. | -| | $button-background | The color used for the button background. | -| | $button-hover-background | The color used for the button background on hover. | -|**$item-active-background** | $item-active-icon-color | The color used for the active tab icon. | -| | $item-active-color | The color used for the active tabs text. | -| | $tab-ripple-color | The color used for the button background. | -| **$item-text-color** | $item-hover-color | The text color used for the tabs on hover if no `$item-hover-background` is provided | -| | $item-icon-color | The color used for the tab icon if no `$item-background` is provided | -| | $item-active-color | The color used for the active tabs text if no `$item-active-background` is provided | -| | $indicator-color | The color used for the active tab indicator if no `$item-background` is provided | -|**$item-icon-color** | $item-hover-icon-color | The color used for the tab icon on hover. | -| | $item-active-icon-color | The color used for the active tab icon. | -| | $indicator-color | The color used for the active tab indicator. | -| **$button-background** | $button-hover-background | The color used for the button background on hover. | -| | $button-color | The color used for the button icon/text color. | -| **$button-color** | $button-disabled-color | The color used for the disabled button icon/text. | -| | $button-ripple-color | The color used for the button background on hover. | -| **$button-hover-background** | $button-hover-color | The color used for the button icon/text color on hover. | - -
- -
-
- -To get started with styling the tabs, we need to import the theming module, where all the theme functions and the `tokens()` mixin are exported: - -```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 . By passing just a few base parameters—such as `$item-background` and `$item-active-color`—you can style your tabs with minimal effort. The theme will automatically generate all necessary background and foreground colors for the various interaction states. - -You can, of course, override any additional parameters to further fine-tune the appearance. - -```scss -$dark-tabs: tabs-theme( - $item-background: #292826, - $item-active-color: #F4D45C, -); -``` - - -Instead of hardcoding the color values like we just did, we can achieve greater flexibility in terms of colors by using the and functions. Please refer to [`Palettes`](./themes/sass/palettes.mdx) topic for detailed guidance on how to use them. - - -If we take a look at the , we will notice that there are even more properties available to us in order to style our tabs. - - -In order to style any component used as part of a tab content, additional themes should be created specific to the respective component. - - -The last step is to **include** the component theme in our application. - -```scss -:host { - @include tokens($dark-tabs); -} -``` - -### Demo - - - -### Styling with Tailwind - -You can style the tabs using our custom Tailwind utility classes. Make sure to [set up Tailwind](./themes/misc/tailwind-classes.mdx) 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-tabs`, `dark-tabs`. - -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 tabs 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/toc.json b/docs/angular/src/content/en/components/toc.json index 9e3f6d8ceb..04c65d3e70 100644 --- a/docs/angular/src/content/en/components/toc.json +++ b/docs/angular/src/content/en/components/toc.json @@ -2226,8 +2226,8 @@ }, { "name": "Tabs", - "href": "tabs.mdx", - "new": false + "href": "layouts/tabs.mdx", + "updated": true }, { "name": "Card", diff --git a/docs/angular/src/content/en/images/anatomy-content-light/tabs-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/tabs-lt-a.png new file mode 100644 index 0000000000..d55df70339 Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/tabs-lt-a.png differ diff --git a/docs/angular/src/content/en/images/tabs/tabs-do-1.png b/docs/angular/src/content/en/images/tabs/tabs-do-1.png new file mode 100644 index 0000000000..4daec372d8 Binary files /dev/null and b/docs/angular/src/content/en/images/tabs/tabs-do-1.png differ diff --git a/docs/angular/src/content/en/images/tabs/tabs-do-2.png b/docs/angular/src/content/en/images/tabs/tabs-do-2.png new file mode 100644 index 0000000000..1f464de4f3 Binary files /dev/null and b/docs/angular/src/content/en/images/tabs/tabs-do-2.png differ diff --git a/docs/angular/src/content/en/images/tabs/tabs-do-not-1.png b/docs/angular/src/content/en/images/tabs/tabs-do-not-1.png new file mode 100644 index 0000000000..d1ffa4631c Binary files /dev/null and b/docs/angular/src/content/en/images/tabs/tabs-do-not-1.png differ diff --git a/docs/angular/src/content/en/images/tabs/tabs-do-not-2.png b/docs/angular/src/content/en/images/tabs/tabs-do-not-2.png new file mode 100644 index 0000000000..6561a3ac33 Binary files /dev/null and b/docs/angular/src/content/en/images/tabs/tabs-do-not-2.png differ diff --git a/docs/xplat/src/assets/images/tabs/tabs-do-1.png b/docs/xplat/src/assets/images/tabs/tabs-do-1.png new file mode 100644 index 0000000000..4daec372d8 Binary files /dev/null and b/docs/xplat/src/assets/images/tabs/tabs-do-1.png differ diff --git a/docs/xplat/src/assets/images/tabs/tabs-do-2.png b/docs/xplat/src/assets/images/tabs/tabs-do-2.png new file mode 100644 index 0000000000..1f464de4f3 Binary files /dev/null and b/docs/xplat/src/assets/images/tabs/tabs-do-2.png differ diff --git a/docs/xplat/src/assets/images/tabs/tabs-do-not-1.png b/docs/xplat/src/assets/images/tabs/tabs-do-not-1.png new file mode 100644 index 0000000000..d1ffa4631c Binary files /dev/null and b/docs/xplat/src/assets/images/tabs/tabs-do-not-1.png differ diff --git a/docs/xplat/src/assets/images/tabs/tabs-do-not-2.png b/docs/xplat/src/assets/images/tabs/tabs-do-not-2.png new file mode 100644 index 0000000000..6561a3ac33 Binary files /dev/null and b/docs/xplat/src/assets/images/tabs/tabs-do-not-2.png differ diff --git a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx index adae5703a0..c8d28297b3 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -86,7 +86,7 @@ This index records what each component's documentation covers today. **Not docum | [Avatar](../layouts/avatar.mdx#accessibility) | Documented | Documented | [Accessibility](../layouts/avatar.mdx#accessibility) | | [Badge](../inputs/badge.mdx#accessibility) | Documented | Documented | [Accessibility](../inputs/badge.mdx#accessibility) | | [Banner](../banner.mdx) | Not documented yet | Not documented yet | — | -| [Bottom Navigation](../tabs.mdx) | Not documented yet | Not documented yet | — | +| [Bottom Navigation](../tabbar.mdx) | Not documented yet | Not documented yet | — | | [Button](../inputs/button.mdx) | Not documented yet | Not documented yet | — | | [Button Group](../inputs/button-group.mdx) | Not documented yet | Not documented yet | — | | [Calendar](../calendar.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../calendar.mdx#keyboard-navigation) | @@ -116,7 +116,7 @@ This index records what each component's documentation covers today. **Not docum | [Slider](../slider/slider.mdx) | Not documented yet | Not documented yet | — | | [Snackbar](../snackbar.mdx) | Not documented yet | Not documented yet | — | | [Switch](../inputs/switch.mdx) | Not documented yet | Not documented yet | — | -| [Tabs](../tabs.mdx) | Not documented yet | Not documented yet | — | +| [Tabs](../layouts/tabs.mdx#accessibility) | Documented | Documented | [Accessibility](../layouts/tabs.mdx#accessibility) | | [Time Picker](../time-picker.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../time-picker.mdx#keyboard-navigation) | | [Toast](../toast.mdx) | Not documented yet | Not documented yet | — | | [Tooltip](../tooltip.mdx#accessibility) | Documented | Not documented yet | [Accessibility](../tooltip.mdx#accessibility) | @@ -165,7 +165,7 @@ This index records what each component's documentation covers today. **Not docum | [Snackbar](../notifications/snackbar.mdx) | Not documented yet | Not documented yet | — | | [Stepper](../layouts/stepper.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../layouts/stepper.mdx#keyboard-navigation) | | [Switch](../inputs/switch.mdx) | Not documented yet | Not documented yet | — | -| [Tabs](../layouts/tabs.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../layouts/tabs.mdx#keyboard-navigation) | +| [Tabs](../layouts/tabs.mdx#accessibility) | Documented | Documented | [Accessibility](../layouts/tabs.mdx#accessibility) | | [Text Area](../inputs/text-area.mdx) | Not documented yet | Not documented yet | — | | [Toast](../notifications/toast.mdx) | Not documented yet | Not documented yet | — | | [Tooltip](../inputs/tooltip.mdx#accessibility--aria-support) | Documented | Documented | [Accessibility](../inputs/tooltip.mdx#accessibility--aria-support) | diff --git a/docs/xplat/src/content/en/components/layouts/carousel.mdx b/docs/xplat/src/content/en/components/layouts/carousel.mdx index 87a074b4bb..9d7bd9ff9f 100644 --- a/docs/xplat/src/content/en/components/layouts/carousel.mdx +++ b/docs/xplat/src/content/en/components/layouts/carousel.mdx @@ -1066,7 +1066,7 @@ Use the template directive with a -**When not to use:** Do not use Carousel for primary navigation, long sequential workflows, or content users must compare side by side. Use [Tabs](../tabs.mdx) for switching between named sections, or [Stepper](../stepper.mdx) for guided sequential tasks. +**When not to use:** Do not use Carousel for primary navigation, long sequential workflows, or content users must compare side by side. Use [Tabs](./tabs.mdx) for switching between named sections, or [Stepper](../stepper.mdx) for guided sequential tasks. @@ -1305,7 +1305,7 @@ Use these related layout components when Carousel is not the best match for the -- [Tabs](../tabs.mdx) - Use Tabs when users need to switch between named sections without slide-style navigation. +- [Tabs](./tabs.mdx) - Use Tabs when users need to switch between named sections without slide-style navigation. - [Stepper](../stepper.mdx) - Use Stepper when users need to complete a guided sequence of steps. diff --git a/docs/xplat/src/content/en/components/layouts/tabs.mdx b/docs/xplat/src/content/en/components/layouts/tabs.mdx index 0957fe8b8e..099235332d 100644 --- a/docs/xplat/src/content/en/components/layouts/tabs.mdx +++ b/docs/xplat/src/content/en/components/layouts/tabs.mdx @@ -1,61 +1,176 @@ --- -title: "{Platform} Tabs Control | Layout Controls | {ProductName}" -description: "{Platform} Tabs component allows users to place tabs at the top and switch between similar data sets. Try it Now" -keywords: "{Platform}, UI controls, web widgets, UI widgets, {Platform} Tabs Component, Infragistics" +title: "{Platform} Tabs Component" +description: "The {ProductName} Tabs component organizes related content into tabs, shows the content of the selected tab, and adds scroll buttons when the tabs don't fit." +keywords: "{Platform} Tabs, {ProductName}, tab header, tab panel, scroll buttons" license: MIT -mentionedTypes: ["Tabs", "Tab", "Icon", "IconButton", "RadioGroup"] +last_updated: "2026-11-04" +relatedComponents: ["Stepper", "Accordion"] +mentionedTypes: ["Tabs", "Tab"] llms: - description: "The {Platform} Tabs is a lightweight and user-friendly component that organizes corresponding content in a tab format or a collection of tabs typically placed horizontally." + description: "The {ProductName} Tabs component organizes related content at the same level of hierarchy into tabs and shows the content of the selected tab." +platformType: web-only --- 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 DoDont from 'igniteui-astro-components/components/mdx/DoDont.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import tabsAnatomy from '@xplat-images/anatomy-content-light/tabs-lt-a.png'; +import tabsDoInformation from '@xplat-images/tabs/tabs-do-1.png'; +import tabsDoNotWorkflow from '@xplat-images/tabs/tabs-do-not-1.png'; +import tabsDoContent from '@xplat-images/tabs/tabs-do-2.png'; +import tabsDoNotMixedContent from '@xplat-images/tabs/tabs-do-not-2.png'; +# Tabs -# {Platform} Tabs Overview +The {ProductName} Tabs component organizes related content at the same level of hierarchy into tabs and shows the content of the selected tab. -The {Platform} Tabs is a lightweight and user-friendly component that organizes corresponding content in a tab format or a collection of tabs typically placed horizontally. The {Platform} Tab enables end-users to easily click through and display different views. There are several features and customization options like tab orientation, templating, built-in header styles, animation, scroll buttons, and more. + -The {ProductName} Tabs organizes and switches between similar data sets. The tabs are placed at the top of the data content. When a tab is selected its corresponding content is displayed. +The selector of the Angular Tabs component is `igx-tabs`. Each `igx-tab-item` in it holds a tab header and the content that the Tabs component shows when the tab is selected. -## {Platform} Tabs Example + -The {Platform} Tabs example below displays three different tabs aligned in a single line so you can navigate across each in a fast and easy way. + - +Each tab holds its header and its content in one element. The Tabs component supports keyboard navigation, and it shows scroll buttons when the tab headers don't fit. -## How to use Tabs with {ProductName} + - +## Live Demo -First, you need to install the {ProductName} by running the following command: + -```cmd -npm install {PackageWebComponents} + + + + + + + + + + +## Anatomy + +The {Platform} Tabs component consists of a container with tab items, optional scroll buttons, and a content area for the selected tab. + + + + + +1. Tabs Container: groups and aligns all tab items
+2. Header Button (optional): navigation arrows appear for tabs that aren't visible in the tab container
+3. Label: text that names the tab and indicates what content it opens
+4. Active Tab Item: a single selectable tab element that is active
+5. Left Icon (optional): icon shown before the label to add context to the tab
+6. Top Icon (optional): icon shown above the label to add context to the tab
+7. Right Icon (optional): icon shown after the label to add context to the tab
+8. Content Area: the panel where content for the selected tab is displayed + + + +The `igc-tabs` element renders the header strip and the scroll buttons. Each `igc-tab` renders its own header and content, and the Tabs component places the content of all tabs below the header strip: + +```text +igc-tabs[role="tablist"] +└─ #shadow-root + └─ div[part="tabs"] // the scrollable header strip + └─ div[part="inner"] + ├─ igc-icon-button[part="start-scroll-button"] // rendered when the headers overflow + ├─ slot // the igc-tab elements + │ └─ igc-tab + │ └─ #shadow-root + │ ├─ div[part="tab-header"][role="tab"] + │ │ └─ div[part="base"] + │ │ ├─ slot[name="prefix"][part="prefix"] + │ │ ├─ div[part="content"] + │ │ │ └─ slot[name="label"] // falls back to the label property + │ │ └─ slot[name="suffix"][part="suffix"] + │ └─ div[part="tab-body"][role="tabpanel"] // visible only for the selected tab + │ └─ slot // the content of the tab + ├─ igc-icon-button[part="end-scroll-button"] // rendered when the headers overflow + └─ div[part="selected-indicator"] + └─ span // moves under the selected tab header ``` - + + +The `igx-tabs` element renders the header strip from the `igx-tab-header` of each tab item and the content area from the `igx-tab-content` of each tab item: + +```text +igx-tabs.igx-tabs +├─ div.igx-tabs-header +│ ├─ button.igx-tabs-header-button // start scroll button, hidden when the headers fit +│ ├─ div.igx-tabs-header__content +│ │ └─ div.igx-tabs-header__wrapper[role="tablist"] +│ │ ├─ div.igx-tabs-header-scroll +│ │ │ └─ igx-tab-header[role="tab"] // one for each igx-tab-item +│ │ │ ├─ [igxPrefix] +│ │ │ ├─ div.igx-tab-header__inner // [igxTabHeaderIcon] above [igxTabHeaderLabel] +│ │ │ └─ [igxSuffix] +│ │ └─ div.igx-tabs-header__active-indicator +│ └─ button.igx-tabs-header-button // end scroll button, hidden when the headers fit +└─ div.igx-tabs-content + └─ igx-tab-content[role="tabpanel"] // one for each igx-tab-item; renders its content only when selected +``` + + -First, you need to the install the corresponding {ProductName} npm package by running the following command: +## Getting Started + +To use the {Platform} Tabs, follow the [{ProductName} Getting Started](../general/getting-started.mdx)[{ProductName} Getting Started](../general-getting-started.mdx) topic for the basic project setup, then add the component for your target platform. + + + +Install the **{PackageCommon}** package: ```cmd -npm install igniteui-react +npm install {PackageCommon} ``` - +Then import the , its theme CSS, and register the component. The registration also registers the `igc-tab` and `igc-icon-button` elements: - +```ts +import { defineComponents, IgcTabsComponent } from 'igniteui-webcomponents'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; -Before using the , you need to import it as follows: +defineComponents(IgcTabsComponent); +``` +Install the **{PackageCommon}** package: + +```cmd +npm install {PackageCommon} +``` + +Then import the and wrappers and the theme CSS: + ```tsx -import { IgrTabs, IgrTab } from "igniteui-react"; +import { IgrTabs, IgrTab } from 'igniteui-react'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; ``` @@ -70,109 +185,590 @@ Register the {ProductName} services: builder.Services.AddIgniteUIBlazor(); ``` -Registering , the client resource module of the component, is **optional**: the component loads its resources when it first renders. Listing it in `builder.Services.AddIgniteUIBlazor(typeof(IgbTabsModule))` can be used to preload resources or to support elements created only on the client (see [Component Modules](../general-getting-started.mdx#component-modules)). +Registering , the client resource module of the , is **optional**: the component loads its resources when it first renders. Listing it in `builder.Services.AddIgniteUIBlazor(typeof(IgbTabsModule))` can be used to preload resources or to support elements created only on the client (see [Component Modules](../general-getting-started.mdx#component-modules)). + +Then link the theme CSS file in the app's host page (**wwwroot/index.html** in a standalone Blazor WebAssembly or Blazor Hybrid app, **Pages/_Host.cshtml** in a Blazor Server app, **Components/App.razor** in a Blazor Web App): + +```razor + +``` - + -```ts -import { defineComponents, IgcTabsComponent } from 'igniteui-webcomponents'; +If your project doesn't use {ProductName} yet, run `ng add igniteui-angular`. Then import the `IGX_TABS_DIRECTIVES` token and add it to the `imports` of your component. The token holds the , the tab item, header, and content components, the header label and icon directives, and the prefix and suffix directives: -defineComponents(IgcTabsComponent); +```ts +import { Component } from '@angular/core'; +import { IGX_TABS_DIRECTIVES } from 'igniteui-angular/tabs'; +// import { IGX_TABS_DIRECTIVES } from '@infragistics/igniteui-angular/tabs'; for licensed package + +@Component({ + selector: 'app-home', + template: ` + + + + Overview + + The overview content. + + + + Details + + The details content. + + + `, + imports: [IGX_TABS_DIRECTIVES] +}) +export class HomeComponent {} ``` +When no tab item is selected and the tab items have content, the Angular Tabs component selects the first tab item on init. + -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.mdx) topic. + + +After registration, render the with a for each section. The label of a tab becomes its header, and the children of the tab become its content: -Simple declaration is done as follows: + ```html - - Content for tab 1 - - - Content for tab 2 - - - Tab 3 - Content for tab 3 - + +

The overview content.

+ + +

The details content.

+ ``` + + +```tsx + + +

The overview content.

+ + +

The details content.

+ + +``` + + + ```razor - - Content for tab 1 + +

The overview content.

+ + +

The details content.

 - - Content for tab 2 + +``` + + + + + +When no tab is selected on the first render, the {Platform} Tabs component selects the first enabled tab. When you later set `selected` to `false` on the selected tab, no tab is selected. + + + +## Usage + +Use the {Platform} Tabs to organize different views of the same information or switch between similar or related data sets. + +### Type + +The Tabs are available in two types - Short, showing only text by default, with the option to have prefix and suffix icons, and Tall, which also has an additional third icon on top of the text. + + + +For a short tab, set the `label` of the tab. For a tall tab, place an Icon and a `` in the `label` slot instead, and the Tabs component shows the icon above the text. The `label` slot takes precedence over the `label` property. Register the icons first, as described in the [Icon](./icon.mdx) topic: + + + + + +```html + + + + + + + + + Cart + + + + Shipping + + +``` + + + + + +```tsx + + + + + + + + + Cart + + + + Shipping + + +``` + + + + + +```razor + + + + + + + + + Cart - Tab 3 - Content for tab 3 + + Shipping ``` + + +To show content before and after the label, such as an icon or a badge, place it in the `prefix` and `suffix` slots of the tab: + + + + + +```html + + + Inbox + 12 + +``` + + + + + +```tsx + + + Inbox + 12 + +``` + + + + + +```razor + + + Inbox + 12 + +``` + + + + + +For a short tab, place a `` with the directive in the `igx-tab-header`. For a tall tab, also add an `igx-icon` with the directive, and the Tabs component shows the icon above the text. Add `IgxIconComponent` to the `imports` of your component next to `IGX_TABS_DIRECTIVES`: + +```html + + + + shopping_basket + Cart + + The cart content. + + + + local_shipping + Shipping + + The shipping content. + + +``` + +To show content before and after the label, such as an icon or a badge, add it to the `igx-tab-header` with the `igxPrefix` and `igxSuffix` directives. The badge below also needs `IgxBadgeComponent` in the `imports`: + +```html + + inbox + Inbox + + +``` + + + + + + + + + + + + + + + +### Responsiveness + +The Tabs can be Content Fit to fill up the available horizontal space by adapting their width, or Fixed with scrolling buttons to navigate a large number of tab items. This allows fitting more content than what is normally possible with the other mode in the same total space. + +The property sets how the {Platform} Tabs component arranges the tab headers: + +- `start` (default): each tab header is as wide as its content, and the headers start at the start edge of the Tabs. +- `center`: each tab header is as wide as its content, and the headers are centered. +- `end`: each tab header is as wide as its content, and the headers end at the end edge of the Tabs. +- `justify`: the tab headers stretch to fill the width of the Tabs. Use it for the Content Fit mode. + + + +```html + + + + + +``` + + + + + +```tsx + + + + + +``` + + + + + +```razor + + + + + +``` + + + + + +```html + + + Podcasts + The podcasts content. + + + Playlists + The playlists content. + + +``` + + + +When the tab headers don't fit, the {Platform} Tabs component shows a scroll button at each end of the header strip, which is the Fixed mode. A scroll button scrolls the strip to the next tab header that is out of view in its direction, and it's disabled when the strip is scrolled to that end. When the user selects a tab, the Tabs component scrolls its header into view. + + + + + + + + + + + + + +### Amount + +For most scenarios, the Tabs need to contain between two and five items. If your use case requires more than five tabs, you should consider the Fixed mode explained above. + + + +You can add and remove tabs at run time. A tab that you add with `selected` set becomes the selected tab, and when you remove the selected tab, the {Platform} Tabs component selects the first enabled tab. + + + + + +You can add and remove tab items at run time, for example with `@for`. When you remove the selected tab item, the Angular Tabs component selects the tab item that takes its index, or the last tab item when the removed one was last. + + + + + + + + + + + + + + + +### States + +Tab Items support Active, Inactive, Active & Hover, Inactive & Hover and Disabled states. In Tabs there is always one Active tab and an arbitrary number of Inactive and Disabled ones. + +Set `selected` on a tab to make it the active tab, and `disabled` to turn it off. Users can't select a disabled tab, and the keyboard navigation skips it. When you disable the selected tab, the {Platform} Tabs component selects the first enabled tab. + + + +```html + + + + + +``` + + + ```tsx - - Content for tab 1 - - - Content for tab 2 - - - Tab 3 - Content for tab 3 - + + + ``` -Tab text can be set either as simple string using the property or by assigning children to the `label` slot. Any remaining children in the `default` slot are rendered as the tab content. + -When using the `label` slot, we recommend using a `` element when you want to provide text and an [``](../layouts/icon.mdx) or [``](../inputs/icon-button.mdx) component when you want to display icons. +```razor + + + + + +``` -### Selection + -The emits event when the user selects an item either by key press or click. The method allows you to select a tab by specifying the or its id. + -If the selected tab is not specified on initial load, the first tab that is not disabled will be selected. +```html + + + Overview + The overview content. + + + Activity + The activity content. + + + Billing + The billing content. + + +``` + + + + + + + + -The default behavior, which selects a tab when the user is navigating with the arrow keys, could be modified by the property. Setting it to `Manual` will focus the next/previous tab on arrow key press, but the tab will be selected only after pressing SPACE or ENTER + -### Disabled Tab + -A tab is disabled by setting the attribute: + + +### Selection +The {Platform} Tabs component emits `igcChange` with the newly selected tab when the user selects a tab with a click or a key. To select a tab in code, call with the tab, or with its `id` or `label`. Read the selected tab from : + ```html - + + + + +``` + +```ts +const tabs = document.querySelector('igc-tabs')!; + +tabs.addEventListener('igcChange', (event) => { + console.log(`Selected: ${event.detail.label}`); +}); + +tabs.select('details'); +console.log(tabs.selectedTab?.label); // "Details" +``` + + + + + +The {Platform} Tabs component calls `onChange` with the newly selected tab when the user selects a tab with a click or a key. To select a tab in code, call with the tab, or with its `id` or `label`: + +```tsx +import { useRef } from 'react'; +import { IgrTab, IgrTabs } from 'igniteui-react'; + +export default function ProfileTabs() { + const tabsRef = useRef(null); + + return ( + <> + ) => console.log(e.detail.label)}> + + + + + + ); +} ``` +The {Platform} Tabs component raises `Change` with the newly selected tab when the user selects a tab with a click or a key. To select a tab in code, call with the `id` or the `Label` of the tab: + ```razor - + + + + + + + +@code { + private IgbTabs Tabs { get; set; } + + private async Task ShowDetails() + { + await Tabs.SelectAsync("Details"); + } + + private void OnTabChange(IgbTabComponentEventArgs e) + { + Console.WriteLine(e.Detail.Label); + } +} +``` + + + + + +Selecting a tab in code, or setting `selected` on a tab, changes the selection without the change event. The Tabs component ignores disabled tabs and values that match no tab. + + + + + +Bind to read and set the index of the selected tab. The Angular Tabs component emits before the selection changes, and you can cancel the change in its handler: + +```html + + + Profile + The profile form. + + + Billing + The billing form. + + +``` + +```ts +import { ITabsSelectedIndexChangingEventArgs } from 'igniteui-angular/tabs'; + +public selectedIndex = 0; +public hasUnsavedChanges = false; + +public onSelectedIndexChanging(event: ITabsSelectedIndexChangingEventArgs) { + if (this.hasUnsavedChanges) { + event.cancel = true; + } +} +``` + +After the selection changes, the Angular Tabs component emits with the previous and the new tab item. These events also fire when you set `selectedIndex` in code. + + + +### Activation + +By default, the {Platform} Tabs component selects a tab as soon as the arrow keys, Home, or End move the focus to its header. Set to `manual` to move only the focus with these keys, and to select the focused tab with Enter or Space. Use the manual activation when showing the content of a tab is slow, for example when it loads data. + + + +```html + + + + ``` @@ -180,134 +776,552 @@ A tab is disabled by setting the ```tsx - + + + + ``` -### Alignment + -The property controls how {Platform} tabs are positioned. It accepts the following values: +```razor + + + + +``` -- `Start` (default): the width of the tab depends on the content (label, icon, both) and all tabs have equal padding. First tab is aligned to the tabs container's left side. -- `Center`: the width of the tab depends on the content and occupies the tabs container's center. -- `End`: the width of the tab depends on the content and all tabs have equal padding. Last tab is aligned to the tabs container's right side. -- `Justify`: all tabs are equal in width and fully fit the tabs container. + -If the space is not enough to fit all tabs, scroll buttons are displayed. + - +```html + + ... + +``` -### Scrolling + -Scroll buttons are shown when the available space is not enough to render all {Platform} tabs. The start scroll button is disabled if the first tab is in view. Respectively, when last tab is in view the end scroll button is disabled. By pressing one of the scroll buttons the tabs are scrolled so the tab in that direction is fully visible, or if it is already visible the previous/next tab in that direction is displayed. +### Do/Don't - +The Tabs are appropriate for organizing information, and one should avoid using them as a way to design workflows and actions that come in a logical sequence, e.g. checkout process or configuration wizard. When using the short Tabs, never combine a text tab with an icon tab in the same bar. Choose one of the two content modes and use it consistently for all the items in the bar. -### Keyboard Navigation + + -|Keys|Description| -|----|-----------| -| ← | Selects previous (next in Right-to-Left mode) tab. If is set to `Manual` only focuses the tab. Scrolls to end if on first tab. | -| → | Selects next (previous in Right-to-Left mode) tab. If is set to `Manual` only focuses the tab. Scrolls to start if on last tab. | -| HOME | Selects the first tab. | -| END | Selects the last tab. | -| ENTER / SPACE | Selects the focused tab when is `Manual` | +Use tabs to organize related information. -### Prefix / Suffix + + -Besides the `label` slot, which can be used to display an icon, text, or both, each tab also provides `prefix` and `suffix` slots for displaying additional content at the beginning and/or the end. When slotting content into the `prefix` and `suffix` slots, we recommend using a `` element for symbols or emojis, and an [``](../layouts/icon.mdx) or [``](../inputs/icon-button.mdx) component for icons. +Avoid tabs for the steps of a sequential workflow, such as a checkout process. - + + -## Styling + + -The component exposes several CSS parts, giving you full control over its style: +Use the same content mode, text or icons, for all tabs in a bar. - + + -| Name | Description | -|--|--| -| `selected-indicator` | The selected indicator. | -| `start-scroll-button` | The start scroll button displayed when the tabs overflow. | -| `end-scroll-button` | The end scroll button displayed when the tabs overflow. | +Avoid combining text tabs and icon tabs in the same bar. + + + + +## Properties + +The {Platform} Tabs component exposes the following properties. See the API reference for the complete type definitions. + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `'start' \| 'end' \| 'center' \| 'justify'` | `'start'` | How the tab headers are arranged in the header strip. | +| | `'auto' \| 'manual'` | `'auto'` | Whether moving the focus to a tab header with the keyboard also selects the tab. | +| | `IgcTabComponent \| null``IgrTab \| null` | `null` | Read-only. The selected tab. | +| | `string` | `''` | Read-only. The `label` of the selected tab, or its `id` when the tab has no `label`. | +| | `IgcTabComponent[]``IgrTab[]` | — | Read-only. The tabs that are direct children of the Tabs. | +| | `string` | `''` | The text of the tab header. The `label` slot takes precedence over it. | +| | `boolean` | `false` | Whether the tab is selected. | +| | `boolean` | `false` | Whether the tab is disabled. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `TabsAlignment` | `Start` | How the tab headers are arranged in the header strip. | +| | `TabsActivation` | `Auto` | Whether moving the focus to a tab header with the keyboard also selects the tab. | +| | `string` | — | The text of the tab header. The `label` slot takes precedence over it. | +| | `bool` | `false` | Whether the tab is selected. | +| | `bool` | `false` | Whether the tab is disabled. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `number` | `-1` | The index of the selected tab item. When no tab item is selected and the tab items have content, the Tabs component selects the first tab item. Supports two-way binding. | +| | `'start' \| 'end' \| 'center' \| 'justify'` | `'start'` | How the tab headers are arranged in the header strip. | +| | `'auto' \| 'manual'` | `'auto'` | Whether moving the focus to a tab header with the keyboard also selects the tab. | +| | `boolean` | `false` | Whether the content animation on selection change is turned off. | +| | `IgxTabItemDirective` | — | Read-only. The selected tab item. | +| | `QueryList` | — | Read-only. The tab items of the Tabs. | +| | `boolean` | `false` | Whether the tab item is selected. Supports two-way binding. | +| | `boolean` | `false` | Whether the tab item is disabled. | + + + + + +## Methods + + + + + +The {Platform} Tabs component exposes the following method. It changes the selection without emitting the change event. + +| Method | Description | +| --- | --- | +| | Selects the tab that you pass, or the tab whose `id` or `label` matches the string that you pass. Ignores disabled tabs and strings that match no tab. | +The {Platform} Tabs component exposes the following methods. Each method also has a synchronous version without the `Async` suffix. + +| Method | Description | +| --- | --- | +| | Selects the tab whose `id` or `Label` matches the string that you pass, without raising `Change`. Ignores disabled tabs and strings that match no tab. | +| | Returns the `Label` of the selected tab, or its `id` when the tab has no `Label`. | + + + +## Events + +The {Platform} Tabs component emits the following events. + + + +| Name | Type | Description | +| --- | --- | --- | +| `igcChange` | `CustomEvent``CustomEvent``EventCallback` | Emitted when the user selects a tab with a click or a key. The event detail holds the selected tab. | + + + + + | Name | Description | -|--|--| -| `headers` | The wrapper which includes the tabs and the scroll buttons. | -| `headers-content` | The container for the tabs which represents the available space for rendering of the tabs. | -| `headers-wrapper` | The wrapper for the tabs and the selected indicator. | -| `headers-scroll` | The container for the tabs. | -| `selected-indicator` | The selected indicator. | -| `start-scroll-button` | The start scroll button displayed when the tabs overflow. | -| `end-scroll-button` | The end scroll button displayed when the tabs overflow. | -| `content` | The container for the content where the data is displayed. | +| --- | --- | +| | Emitted with before the selected index changes. Set `cancel` to keep the current tab, or change `newIndex` to select another tab. | +| | Emitted with the new index, a `number`, after the selected index changes. Enables the `[(selectedIndex)]` two-way binding. | +| | Emitted with , which holds the previous and the new tab item, after the selected tab item changes. | +| | Emitted with a `boolean` when the tab item is selected or deselected. Enables the `[(selected)]` two-way binding. | -The component exposes the following CSS parts: +## Styling + +The {Platform} Tabs component takes its colors from the theme. Change them with the following CSS variables: + +| Variable | What it changes | +| --- | --- | +| `--ig-tabs-item-background` | The background of the tab headers. | +| `--ig-tabs-item-text-color` | The text color of the tab headers. | +| `--ig-tabs-item-icon-color` | The icon color of the tab headers. | +| `--ig-tabs-item-hover-background` | The background of a hovered or focused tab header. | +| `--ig-tabs-item-hover-color` | The text color of a hovered or focused tab header. | +| `--ig-tabs-item-active-background` | The background of the selected tab header. | +| `--ig-tabs-item-active-color` | The text color of the selected tab header. | +| `--ig-tabs-item-active-icon-color` | The icon color of the selected tab header. | +| `--ig-tabs-item-disabled-color` | The text color of a disabled tab header. | +| `--ig-tabs-item-disabled-icon-color` | The icon color of a disabled tab header. | +| `--ig-tabs-indicator-color` | The color of the indicator under the selected tab header. | +| `--ig-tabs-button-background` | The background of the scroll buttons. | +| `--ig-tabs-button-color` | The icon color of the scroll buttons. | +| `--ig-tabs-button-hover-background` | The background of a hovered scroll button. | +| `--ig-tabs-button-disabled-color` | The icon color of a disabled scroll button. | +| `--ig-tabs-header-background` | The background of the header strip behind the tab headers. | + + + +The `igc-tabs` element exposes the following CSS parts: + +| Part | What it styles | +| --- | --- | +| `start-scroll-button` | The start scroll button. | +| `end-scroll-button` | The end scroll button. | +| `selected-indicator` | The indicator under the selected tab header. | + +The `igc-tab` element exposes the following CSS parts: + +| Part | What it styles | +| --- | --- | +| `tab-header` | The header of the tab. | +| `prefix` | The container of the `prefix` slot. | +| `content` | The container of the `label` slot. | +| `suffix` | The container of the `suffix` slot. | +| `tab-body` | The content of the tab, which is visible only for the selected tab. | -|Name|Description| -|--|--| -| `content` | Tab header's label slot container. | -| `prefix` | Tab header's label prefix. | -| `suffix` | Tab header's label suffix. | -| `tab-header` | The header of a single tab. | -| `tab-body` | Holds the body content of a single tab, only the body of the selected tab is visible. | + -```css -igc-tab::part(tab-header), -igc-tabs::part(inner)::after { - --item-background: var(--ig-surface-600); - --border-color: var(--ig-success-300); -} +### Sass Theming -igc-tab::part(tab-body), -igc-tab[selected] igc-icon { - --item-active-icon-color: var(--ig-success-300); +When you modify a primary property, all related dependent properties are automatically updated to reflect the change. The primary parameters of the `tabs-theme` function are `$item-background`, from which the theme derives the colors of all tab states, and `$item-active-color`, from which it derives the indicator color. Create a theme with the function and include it with the `tokens()` mixin, which emits the matching `--ig-tabs-*` variables in the scope where you include it. + + + +```scss +@use "igniteui-angular/theming" as *; + +$custom-tabs-theme: tabs-theme( + $item-background: #292826, + $item-active-color: #f4d45c +); + +:host { + @include tokens($custom-tabs-theme); } +``` + + -igc-tab:not([selected]) igc-icon { - --item-icon-color: var(--ig-gray-500); + + +The Sass functions come from the `igniteui-theming` package. See the [Theming](../themes/overview.mdx) topic for the Sass setup. + +```scss +@use "igniteui-theming" as *; + +$custom-tabs-theme: tabs-theme( + $item-background: #292826, + $item-active-color: #f4d45c +); + +:root { + @include tokens($custom-tabs-theme); } +``` + + + +### CSS Variables -igc-tabs::part(start-scroll-button), -igc-tabs::part(end-scroll-button) { - --background: var(--ig-surface-600); - --hover-background: var(--ig-surface-700); - --active-background: var(--ig-surface-700); - --disabled-background: var(--ig-gray-100); - --button-color: var(--ig-gray-700); - --button-hover-color: var(--ig-gray-800); - --button-disabled-color: var(--ig-gray-300); - --border-color: var(--ig-surface-600); +Set the CSS variables on a Tabs component or on a container when you need local styling without a Sass build step: + +```css +.profile-tabs { + --ig-tabs-item-active-color: #e41c77; + --ig-tabs-indicator-color: #e41c77; } +``` + + +Use the CSS parts for other styles: + +```css igc-tab::part(tab-header) { - --item-hover-color: var(--ig-success-500); + font-weight: 600; } -igc-tab::part(tab-header)::before { - --border-color--hover: var(--ig-gray-500); +igc-tabs::part(selected-indicator) { + opacity: 0.8; } ``` - + + -## API Reference + - - - - - + + + + + + + + +### Styling with Tailwind + +You can style the {Platform} Tabs using our custom Tailwind utility classes. Make sure to [set up Tailwind](../themes/misc/tailwind-classes.mdx)[set up Tailwind](../themes/tailwind.mdx) first. + + + +Import the Ignite UI utilities in your global stylesheet: + +```css +@import "tailwindcss"; +@import "igniteui-theming/tailwind/utilities/material.css"; +``` + +Use the `light-tabs` or `dark-tabs` class for the corresponding theme, and override the generated CSS variables with arbitrary properties: + +```html + + ... + +``` + +The exclamation mark (`!`) gives the Tailwind utility precedence over the default theme styles of the Tabs. + + + + + +Set the `--ig-tabs-*` CSS variables with Tailwind arbitrary properties: + + + + + +```html + + ... + +``` + + + + + +```tsx + + ... + +``` + + + + + +```razor + + ... + +``` + + + + + + + + + + + + + + + +## Accessibility + +The {Platform} Tabs component uses the roles of the WAI-ARIA tabs pattern: users reach the tab headers with the Tab key, move between them with the arrow keys, and select a tab to show its content. + +### Keyboard Interaction + + + +The header strip of the {Platform} Tabs component is a single tab stop: only the selected tab header is in the tab order, or the first enabled tab header when no tab is selected. The content of the selected tab is the next tab stop. The following keys work while a tab header has the focus: + +| Key | Action | +| --- | --- | +| Tab / Shift + Tab | Moves the focus out of the header strip, to the content of the selected tab or to the previous focusable element. The Tabs component doesn't handle these keys. | +| Arrow Right | Moves the focus to the next enabled tab header, and from the last one to the first. In a right-to-left layout, moves it to the previous one. With the `auto` activation, also selects the tab. | +| Arrow Left | Moves the focus to the previous enabled tab header, and from the first one to the last. In a right-to-left layout, moves it to the next one. With the `auto` activation, also selects the tab. | +| Home | Moves the focus to the first enabled tab header. With the `auto` activation, also selects the tab. | +| End | Moves the focus to the last enabled tab header. With the `auto` activation, also selects the tab. | +| Enter / Space | Selects the focused tab. | + +The {Platform} Tabs component handles these keys on `keydown`: + +- It prevents their default action, so the arrow keys, Home, End, and Space don't scroll the page. +- A key that you hold doesn't repeat its action. +- A key that you press together with Shift, Ctrl, Alt, or Meta does nothing. +- The Tabs component scrolls the header that receives the focus into view. + +With a pointer, a click on a tab header focuses and selects the tab. A disabled tab ignores clicks. The scroll buttons aren't in the tab order. + + + + + +Only the selected tab header of the Angular Tabs component is in the tab order, so the header strip is a single tab stop. When no tab item is selected, no tab header is in the tab order. The content of the selected tab is the next tab stop. The following keys work while a tab header has the focus: + +| Key | Action | +| --- | --- | +| Tab / Shift + Tab | Moves the focus out of the header strip, to the content of the selected tab or to the previous focusable element. The Tabs component doesn't handle these keys. | +| Arrow Right | Moves the focus to the next enabled tab header, and from the last one to the first. In a right-to-left layout, moves it to the previous one. With the `auto` activation, also selects the tab. | +| Arrow Left | Moves the focus to the previous enabled tab header, and from the first one to the last. In a right-to-left layout, moves it to the next one. With the `auto` activation, also selects the tab. | +| Home | Moves the focus to the first enabled tab header. With the `auto` activation, also selects the tab. | +| End | Moves the focus to the last enabled tab header. With the `auto` activation, also selects the tab. | +| Enter / Space | With the `manual` activation, selects the focused tab by clicking its header. | + +With a pointer, a click on a tab header selects the tab when the tab item has content. A disabled tab header ignores clicks. The scroll buttons aren't in the tab order. + + + +### Screen Readers / ARIA + + + +The {Platform} Tabs component renders the following roles and attributes: + +| Element | Role | Attributes | +| --- | --- | --- | +| `igc-tabs` | `tablist` | `aria-orientation="horizontal"`, set through element internals | +| The `tab-header` part of each tab | `tab` | `aria-selected`, `aria-disabled`, `aria-controls` that points to the content of the tab, `aria-posinset`, and `aria-setsize` | +| The `tab-body` part of each tab | `tabpanel` | `aria-labelledby` that points to the header of the tab | + +The {Platform} Tabs component also behaves as follows for assistive technology: + +- A tab takes its accessible name from its header content: the `label` property or the `label` slot, and the content of the `prefix` and `suffix` slots. +- The content of the tabs that aren't selected is hidden and `inert`, so assistive technology and the keyboard skip it. +- The `aria-posinset` and `aria-setsize` attributes of each tab header give screen readers the position of the tab in the set, such as "2 of 3". +- The Tabs component doesn't use a live region. A changed selection reaches assistive technology through the `aria-selected` state and the focus. + + + + + +The Angular Tabs component renders the following roles and attributes: + +| Element | Role | Attributes | +| --- | --- | --- | +| The `div.igx-tabs-header__wrapper` element in the header | `tablist` | — | +| `igx-tab-header` | `tab` | `aria-selected`, `aria-disabled`, and, when the tab item has content, an `id` and `aria-controls` that points to the content | +| `igx-tab-content` | `tabpanel` | `aria-labelledby` that points to the header of the tab item | + +The Angular Tabs component also behaves as follows for assistive technology: + +- A tab takes its accessible name from the content of its `igx-tab-header`. +- The Tabs component renders the content of the selected tab item only, so the content of the other tab items isn't in the DOM. +- Tab items without `igx-tab-content`, such as the tabs that drive the router, get no `id` and `aria-controls`. +- The Tabs component doesn't use a live region. A changed selection reaches assistive technology through the `aria-selected` state and the focus. + + + +### Accessibility Compliance + +Infragistics documents {ProductName} accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) topic. + +| Criterion | How the component complies | +| --- | --- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | The `tablist`, `tab`, and `tabpanel` roles expose the structure, and each tab panel is labeled by its tab header through `aria-labelledby`. | +| [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color) | In the Material, Fluent, and Indigo themes, the selected tab header shows an indicator line under it, so the selection doesn't depend on color alone. | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) | The arrow keys, Home, and End move between the tab headers, and Enter and Space select the focused tab with the `manual` activation. | +| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap) | The Tabs component doesn't handle the Tab key, so Tab and Shift + Tab move the focus out of the header strip. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order) | The header strip is a single tab stop, followed by the content of the selected tab. | +| [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible) | The focused tab header takes the hover colors of the theme, so it stands out from the other tab headers. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) | Each tab header exposes the `tab` role, a name from its content, and its selected and disabled states through `aria-selected` and `aria-disabled`. | + +Your responsibilities: + +- Give every tab a text label that names its content. A tab takes its accessible name from its header content, so a header with an icon only needs a text alternative. See [Type](#type). +- When you override the theme colors, keep a contrast ratio of at least 3:1 between the selected indicator and the background, as [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast) requires, and keep the focused tab header distinct from the other headers. +- Don't use the Tabs for the steps of a sequential process. Use a Stepper, which communicates the order of the steps. +- Keep a tab item selected, so that keyboard users can reach the header strip, and set the `manual` activation for tabs that drive the router. + +## API References + +The {Platform} Tabs API reference lists the complete API surface for the target platform. + + + +- +- + + + + + +- +- +- +- +- +- +- + + + +## Dependencies + +The {Platform} Tabs component requires a theme to apply its colors and sizes. See the framework-specific setup in [**Getting Started**](../general/getting-started.mdx)[**Getting Started**](../general-getting-started.mdx). + + + +The scroll buttons of the Angular Tabs use the Icon Button and the Icon, and the `theme()` mixin includes their styles together with the Tabs styles. + + + + + +The registration of the `IgcTabsComponent` also registers the `igc-tab` element and the `igc-icon-button` element of the scroll buttons. Register the components that you place in the tabs, such as the Icon, separately. + + + + + +Register the modules of the components that you place in the tabs, such as the `IgbIconModule`, separately. + + ## Additional Resources +The following resources provide more {Platform} Tabs guidance and project support: + +- [Tabs - Design System Component](https://www.infragistics.com/products/indigo-design/help/components/tabs) - [{ProductName} **Forums**]({ForumsLink}) -- [{ProductName} **GitHub**]({GithubLink}) \ No newline at end of file +- [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + +The {Platform} Tabs component shows one section of related content at a time. Use these components when the content needs a different structure: + +- [Stepper](../stepper.mdx)[Stepper](./stepper.mdx) - Use Stepper when users complete a sequence of steps, such as a checkout process. +- [Accordion](./accordion.mdx) - Use Accordion when users need to expand several sections of a vertical list at the same time. +- [Bottom Navigation](../tabbar.mdx) - Use Bottom Navigation to switch between the top-level views of a mobile app from the bottom of the screen. + +## FAQ + +These questions cover common {Platform} Tabs setup, accessibility, and usage scenarios. + + + + Set the `selectedIndex` property of the Angular Tabs, or set the `selected` input of a tab item to `true`. The Angular Tabs component emits `selectedIndexChanging` and `selectedItemChange` for these changes too.Call the `select` method of the {Platform} Tabs with a tab, or with the `id` or the `label` of a tab, or set `selected` on the tab. The {Platform} Tabs component doesn't emit the change event for a selection that you make in code.Call the `SelectAsync` method of the Blazor Tabs with the `id` or the `Label` of a tab, or set `Selected` on the tab. The Blazor Tabs component doesn't raise `Change` for a selection that you make in code. + + + Yes. Handle the `selectedIndexChanging` event of the Angular Tabs and set `cancel` to `true` to keep the current tab, for example while a form in it has unsaved changes. To make a tab unavailable at all times, set `disabled` on the tab item.The change event of the {Platform} Tabs component isn't cancelable, because the {Platform} Tabs component emits it after the selection changes. Set `disabled` on the tabs that users must not open, and enable them when they become available. + + + No. The Angular Tabs component adds the content of the selected tab item to the DOM and removes the content of the other tab items from it. Code that queries the DOM, such as `document.querySelector`, finds only the content of the selected tab item.Yes. The {Platform} Tabs component keeps the content of every tab in the DOM, hides the content of the tabs that aren't selected, and makes it `inert`, so users and assistive technology can't reach it until its tab is selected. + + + No. The {Platform} Tabs component organizes related information that users can open in any order, and it doesn't communicate an order of steps. Use the {Platform} Stepper for a sequential process, such as a checkout or a configuration wizard. + + diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index 67816f5110..b732146619 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -3120,11 +3120,9 @@ ] }, { - "exclude": [ - "Angular" - ], "name": "Tabs", "href": "layouts/tabs.mdx", + "updated": true, "include": [ "Web" ]