From 4ab9ed1d133842f65134279954fe392c483d9767 Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 9 Jul 2026 11:36:11 +0300 Subject: [PATCH 1/8] feat(docs): Add skill for documentation audit --- .claude/skills/igniteui-doc-topics/SKILL.md | 135 +++++++ .../references/audit-rubric.md | 156 +++++++++ .../references/diataxis-cheatsheet.md | 72 ++++ .../references/house-style.md | 329 ++++++++++++++++++ 4 files changed, 692 insertions(+) create mode 100644 .claude/skills/igniteui-doc-topics/SKILL.md create mode 100644 .claude/skills/igniteui-doc-topics/references/audit-rubric.md create mode 100644 .claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md create mode 100644 .claude/skills/igniteui-doc-topics/references/house-style.md diff --git a/.claude/skills/igniteui-doc-topics/SKILL.md b/.claude/skills/igniteui-doc-topics/SKILL.md new file mode 100644 index 0000000000..976b831ce1 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/SKILL.md @@ -0,0 +1,135 @@ +--- +name: igniteui-doc-topics +description: >- + Author or audit Ignite UI documentation topics — component pages, how-to guides, conceptual + overviews, and category indexes — for both the Angular doc set and the cross-platform (React / + Web Components / Blazor) doc set. Applies the Diátaxis framework mapped onto Ignite UI's house + templates: canonical section order, fixed heading names, frontmatter (including `llms.description` + and the `relatedComponents` trigger), `.mdx` sample embeds, and per-framework token/PlatformBlock + mechanics. Use this whenever someone asks to write, draft, create, review, audit, fix, or + standardize a documentation topic, tutorial, guide, reference page, or concept overview for Ignite + UI — even if they just say "write docs for the X component" or "review this topic" without naming + Diátaxis or the templates. Also use it when deciding what *kind* of documentation a page should be, + or when a topic mixes tutorial / how-to / reference / explanation content that should be separated. +--- + +# Ignite UI doc topics + +Write and audit Ignite UI documentation topics so every page has the same predictable shape — easy +for developers to read and for AI assistants to answer from. The engine is **Diátaxis** (four +documentation modes) applied through **Ignite UI's house templates**. + +## Two modes of operation + +- **Create** — draft a new topic (component, concept/guide, or category/index) to the standard. +- **Audit** — review an existing topic against the standard and return an issues-and-fixes report. + +Detect which from the request ("write/draft/create" → Create; "review/audit/check/fix/standardize" → +Audit). If a topic file or content is supplied, default to Audit unless they ask for a rewrite. + +## Reference files — load what the task needs + +- `references/diataxis-cheatsheet.md` — the four modes + the compass. Load when classifying a topic + or diagnosing mode-bleed. +- `references/house-style.md` — sections, order, naming, frontmatter, sample/token mechanics, both + doc sets. Load for **every** create or audit. +- `references/audit-rubric.md` — the checkable rules + report format. Load for **every** audit. + +Read `house-style.md` before writing or judging any topic — it carries the mechanical details +(frontmatter fields, ``/`` syntax, Angular-vs-xplat differences) that aren't +in this file. + +## Step 0 — Classify with the compass (always first) + +Before writing or auditing, decide what *kind* of documentation the page is, using the compass from +the cheat-sheet: + +> **action or cognition?** × **acquisition (study) or application (work)?** +> → tutorial · how-to · reference · explanation + +- A **component page** is a *composite* (see below). +- A **concept / guide overview** is **explanation**. +- A **category / index overview** is **reference/navigation** (a map). +- A standalone **"How to …" article** is a **how-to guide** — keep it single-mode. + +If a request is ambiguous ("document X"), state which topic type you're producing and why, in one +line, before proceeding. + +## The composite-topic principle (the heart of this skill) + +Pure Diátaxis says keep the four modes in **separate** documents. Ignite UI **component topics +deliberately don't** — one page carries decision guidance (Overview), a live demo, a how-to +(Getting Started/Usage), do/don't guidance (Best Practices), and reference tables +(Properties/Methods/Events). That is fine **because each *section* owns exactly one mode.** The rule +that makes it work: + +> **One section, one mode. No mode-bleed.** Each section stays in its assigned Diátaxis mode; when a +> second mode wants in, move it to the section that owns it and cross-link. + +Section → mode map (full contents in `house-style.md`): + +| Section | Mode | Stays out of | +|---|---|---| +| Overview: When to Use / When Not to Use | **explanation** | install steps, API detail | +| Live Demo | demonstration (action) | prose/explanation | +| Anatomy: visual + DOM tree / skeleton | orientation (reference) | opinion, install steps | +| Getting Started, Usage | **how-to** | *why* explanations, exhaustive option lists | +| Best Practices: do/don't guidance | **explanation** | install steps, code, API detail | +| Properties / Methods / Events | **reference** | instructions, opinion | +| Styling (`### Sass Theming`, `### Tailwind`, …) | how-to (steps) + reference (tables) | conceptual essays | +| Accessibility | reference (keyboard/ARIA/compliance tables) | tutorials, marketing, unverified conformance claims | +| Troubleshooting | how-to (cause → fix) | background theory | +| API References / Dependencies / Additional Resources | reference / navigation | new teaching | + +Concrete mode-bleed to catch: a *why* paragraph inside **Usage** (→ move to When to Use or a concept +topic, link back); "how to build X" prose inside **Properties** (→ move to Usage; keep the table +descriptive); an exhaustive option list written out in **Usage** prose (→ move to the table). The +cheat-sheet's "two classic confusions" section explains the reasoning. + +## Create workflow + +1. **Classify** (Step 0). Name the topic type. +2. **Pick the doc set & framework.** Angular set = its own file, plain prose. xplat set = one file + for React/WC/Blazor using `{Platform}`/`{ProductName}` tokens and ``. Load + the relevant details from `house-style.md`. +3. **Write frontmatter first** — `title`, `description` (answer-shaped, ≤~160 chars), `keywords`, + `license`, `llms.description`, `mentionedTypes` (xplat), and `relatedComponents` if the component + has close siblings (this lets **Overview**'s **When Not to Use** sub-heading name the specific + sibling instead of speaking generically). +4. **Lay out the canonical sections** in order for that topic type, required ones always present. + Feature-specific content goes as sub-headings under **Usage**, never as new top-level sections. +5. **Fill each section in its mode.** Lead every section with one plain, specific sentence. Put + reference in tables. Embed exactly one top ``, then Usage samples only for distinct tasks + (soft max 5/page). Phrase When-Not-to-Use and Troubleshooting as the reader's real questions. +6. **Self-check against the rubric** before presenting — especially mode-bleed (C-checks) and + metadata (D-checks). Fix, then deliver the `.mdx`. + +## Audit workflow + +1. **Classify** the topic and identify its doc set (Angular vs xplat) and type. +2. **Run every check** in `references/audit-rubric.md` — structure/order (A), naming (B), Diátaxis + mode integrity (C), metadata/AI-readiness (D), samples/links (E). For mode integrity, run the + compass on each section and flag drift. +3. **Report** in the rubric's exact format: Verdict → Summary → Findings (each with Where / Issue / + Principle / Fix) → Quick wins. Order findings Error → Warning → Suggestion. +4. Keep every **Fix** concrete and applyable (the corrected heading, the sentence to move, the table + to add). If the topic is already clean, say so and note what it does well — don't invent problems. + +## Grounding notes + +- The live `vnext` repo is **pre-standardization**: expect drifted headings (`## Angular Rating + Example`, `## Configuration`) and a missing `relatedComponents` field. Author to the **target** + standard; audit against it while recognizing current reality. +- **Invent no verifiable identifier (zero-risk rule).** Never emit a guessed tag, class, package, + property, method, event, CSS part, or theming variable — a plausible-but-wrong name a reader copies is + worse than a visible gap. Use an identifier only when verified (typed API source, an existing topic, + or the user); otherwise write `‹VERIFY: …›`. For Properties/Methods/Events, emit the fixed column + headers plus a build-injection note and leave the rows to the generator. React/Blazor wrapper symbols + resolve to the `igc` core — prefer verified `igc` usage and mark unconfirmed wrapper names `‹VERIFY:…›`. + (Full detail in `house-style.md` → "Never fabricate API identifiers".) +- Prefer paraphrase and the standard section names over copying any existing topic's prose verbatim. +- **Write in one voice and verify every claim** (see house-style → *Voice & tone* and *Verify every + claim against the component*): instruct in the imperative/second person, and check every factual + statement — defaults, behavior, version support, DOM — against the component's typed source or the + official API/framework docs before writing it or recommending it as an edit. Don't "correct" prose + into a plausible claim you haven't verified. diff --git a/.claude/skills/igniteui-doc-topics/references/audit-rubric.md b/.claude/skills/igniteui-doc-topics/references/audit-rubric.md new file mode 100644 index 0000000000..3dbc1bca03 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/audit-rubric.md @@ -0,0 +1,156 @@ +# Audit rubric + +The checkable rules for **audit mode**, and the report format to produce. Every finding maps to a +concrete rule below (structure, naming, Diátaxis mode, or metadata) and to a fix. Detail lives in +`house-style.md`; the *why* behind mode findings lives in `diataxis-cheatsheet.md`. + +## Severity + +- **Error** — breaks the standard or misleads readers/AI. Must fix. +- **Warning** — drift or a gap that degrades quality. Should fix. +- **Suggestion** — polish; author's judgment. + +## Checks + +### A. Structure & order +- A1 (Error) A required section is missing (Overview, Live Demo, Getting Started, Usage, + Best Practices, Properties, Accessibility, API References, Additional Resources on a component + topic). +- A2 (Warning) Sections are present but out of the canonical order. +- A3 (Warning) A conditional section sits in the wrong slot. +- A4 (Error) A feature-specific top-level `##` exists that should be a sub-heading under **Usage**. +- A5 (Error) **Overview** is not the first section after the title/definition, or **Live Demo** is + missing or doesn't immediately follow **Overview**. +- A6 (Suggestion) >10 live samples on one page (soft cap) — consider splitting. Up to 10 is fine; + only flag when a page clearly sprawls past that. +- A7 (Warning) **When to Use / When Not to Use** are not `###` sub-headings under the `## Overview` + section — e.g. they appear as top-level `##`, or are still nested under **Anatomy** (the + pre-revision slot). +- A8 (Suggestion) **Anatomy** is missing its opening screenshot/GIF (or a `{/* TODO */}` marker for a + not-yet-available asset), or is missing the DOM tree / skeleton. +- A9 (Warning) **Accessibility** is missing one of its three required `###` sub-sections — + **Keyboard Interaction**, **Screen Readers / ARIA**, **Accessibility Compliance** — or has them out + of order. +- A10 (Warning) **Best Practices** contains install steps, code snippets, a property table, or other + reference/how-to content that belongs in Usage, Properties, or Accessibility instead of do/don't + guidance. + +### B. Naming +- B1 (Warning) A heading uses a drifted name with a standard equivalent (see reconciliation table). + Report both: `"Configuration" → Properties`. +- B2 (Warning) Non-standard one-off heading (e.g. `## Angular Rating Example`) → map to standard. +- B3 (Suggestion) Singular/plural or casing mismatch (`API Reference` → `API References`). +- B4 (Warning) H1 carries a framework prefix or an "Overview" suffix → standard H1 is + `‹Component› Component` (e.g. `# Angular Avatar Component Overview` → `# Avatar Component`). +- B5 (Warning) A **Usage** sub-heading repeats the component name (`### Avatar Shape` → `### Shape`). + +### C. Diátaxis mode integrity (mode-bleed) +Run the compass on each section; flag content that has drifted out of the section's assigned mode. +- C1 (Warning) **Explanation inside Usage/Getting Started** ("The reason this works is…") — move to + When to Use / a concept topic and link. +- C2 (Warning) **Instruction inside a reference section** (Properties/Methods/Events telling the + reader *how to* build something) — move to Usage; keep the table descriptive. +- C3 (Warning) **Reference dumped into Usage** (exhaustive option lists in prose) — move to the table. +- C4 (Warning) **When to Use that only says when to *use*** it, never when *not* to — the + When-Not-to-Use redirect is the high-value half. +- C5 (Suggestion) Tutorial-style hand-holding in a how-to (or vice-versa) — match the audience. +- C6 (Warning) **Styling content inside Usage** (CSS-var overrides, `color`/background + snippets) — move to the **Styling** section; Styling should also open with a `` of the result. +- C7 (Warning) **Usage doesn't cover every public input**, or documents each option in isolation + instead of stating the behavioral relationship once (e.g. the content-type priority). +- C8 (Warning) **Best Practices drifts into another mode** — install/code steps (belongs in Getting + Started/Usage), an exhaustive option table (belongs in Properties), or conformance claims (belongs + in Accessibility) instead of do/don't guidance. + +### D. Metadata & AI-readiness +- D1 (Warning) `relatedComponents` is set but **Overview**'s **When Not to Use** doesn't name the + specific sibling(s) by name and link them — or vice-versa, it names a sibling that isn't listed in + `relatedComponents`. +- D2 (Warning) Missing/weak `description` or `llms.description` (not answer-shaped, or >~160 chars). +- D3 (Warning) Section opens with no plain lead sentence, or with empty boilerplate. +- D4 (Warning) A section relies on "as mentioned above" / isn't self-contained. +- D5 (Warning) Properties/Methods/Events appear hand-written rather than from the typed source. +- D6 (Suggestion) Styling variables undocumented where the component is themeable. +- D7 (Warning) xplat: hard-coded framework name where a `{Platform}`/`{ProductName}` token belongs, or + framework-specific content not wrapped in ``. +- D8 (Error) An API identifier (tag, class, package, property, method, event, CSS part, theming + variable) appears to be fabricated/unverifiable, or an unresolved `‹VERIFY:…›` placeholder was left + in. Reference values must trace to the typed API source. +- D9 (Error) A **claim** contradicts or isn't verifiable against the component — a wrong default, + value range, precedence/fallback behavior, version-support statement, deprecation, or DOM + description. Verify against the typed source / official API (and official framework docs for + version behavior); if unverifiable, don't assert it. +- D10 (Warning) **Voice/tone drift** — prose isn't imperative/second-person present tense, mixes + first-person-plural narration ("we create") with how-to, or carries filler ("simply", "just") or + marketing inside instructional prose. +- D11 (Error) **Blanket or unverified accessibility-conformance claim** — "fully accessible" / + "WCAG compliant" prose, a conformance target (WCAG level, Section 508, EN 301 549) with no official + source, a conformance-table row not traceable to behavior verified on the page or in source, an + "N/A" filler row for an irrelevant criterion, or an invented testing/AT matrix or VPAT link. + Fix: criterion-level rows tied to observable behavior, or `‹VERIFY:…›`. + +### E. Samples & links +- E1 (Warning) `` missing an `alt`. +- E2 (Suggestion) Near-duplicate samples that teach the same task. +- E3 (Warning) Hand-written API URL instead of ``. +- E4 (Warning) `
` or `` placed directly before or after a ``, code fence, + or table (dividers separate prose only). +- E5 (Warning) A `` sets both `fitContent` and `height` — they are mutually exclusive. + `fitContent` sizes the iframe to the component, so remove `height`. +- E6 (Error) An `` whose `type` has no generated reference page — typically an abstract/base + class (e.g. `ButtonBase`): the link renders (e.g. `IgrButtonBase`) but points nowhere. Verify the + `type` appears as an `` target elsewhere in the doc set; link base-class members through + the concrete component (`type="Button" member="href"`) instead. + +### F. Formatting & altitude +- F1 (Suggestion) A `ul`/`ol` with a single item that should be a paragraph. +- F2 (Warning) A deprecated/legacy setup (e.g. NgModule) shown **above** the current recommended + approach (standalone) — reorder so current is first, legacy after and marked as such. +- F3 (Suggestion) The **Styling** section doesn't open with a `` of the styled result, or its + first subsection isn't `### Sass Theming`. +- F4 (Suggestion) **Getting Started** repeats the generic install boilerplate (the `ng add` command + with the "install the library first / read getting started" prose that is identical on every page) + instead of compressing it to a **one-line prerequisite link** and leading with the component-specific + import. +- F5 (Warning) An inline Properties/Styling-Variables table has rows not verified from source, or is + presented as generated when the repo has no generator (curated + `` is the current rule). +- F6 (Warning) A version-migration note lives inside a code-fence comment, or legacy/alternative setup + (e.g. NgModule) is scattered outside **Troubleshooting** → move it into Troubleshooting as + question → cause → fix; keep Getting Started and samples on the current path only. +- F7 (Warning) An **inline** fenced code snippet uses a deprecated API or outdated framework idiom + (e.g. `standalone: true`, `*ngIf`/`*ngFor`, an old import path) → modernize it. Scope is authored + snippets only; **live `` embeds are out of scope** (fix those in the sample project), and + legacy snippets deliberately kept in **Troubleshooting** are exempt. +- F8 (Warning) The Styling section has **per-theme variable tables** (the legacy + `.theme-switcher-wrapper` / `.theme-table` tabbed markup) or a **default-value column** in the + Styling Variables table. Every theme extends the same base schema — the variable *set* is identical + across themes, only the default values differ — so per-theme tabs document a difference that doesn't + exist, and defaults are per-theme data for the generated API reference. Fix: collapse to **one + two-column table (variable · what it changes)**. + +## Report format + +Produce this exact shape: + +``` +# Audit: ( · ) + +**Verdict:** +**Summary:** <2–3 sentences: biggest issues and the through-line.> + +## Findings +### · · +- **Where:**
+- **Issue:** +- **Principle:** +- **Fix:** + + + +## Quick wins + +``` + +Keep every **Fix** concrete and applyable — the corrected heading text, the exact sentence to move and +where, the table columns to add. Group findings by severity, most severe first. If the topic is clean, +say so plainly and note what it does well rather than inventing problems. diff --git a/.claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md b/.claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md new file mode 100644 index 0000000000..2ef9bceeac --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md @@ -0,0 +1,72 @@ +# Diátaxis cheat-sheet + +Condensed from https://diataxis.fr (tutorials, how-to, reference, explanation, compass). +This is the *reasoning layer*. For how the four modes attach to Ignite UI sections, see +`house-style.md`. Read this whenever you're unsure what kind of content a topic — or a single +section — should be. + +## The compass (use this first, every time) + +Two questions decide the mode. Ask them of the *content in front of you* or the *user need*: + +| If the content… | …and serves the user's… | …then it is… | +| ----------------- | ----------------------- | ------------ | +| informs **action** | **acquisition** of skill (study) | a **tutorial** | +| informs **action** | **application** of skill (work) | a **how-to guide** | +| informs **cognition** | **application** of skill (work) | **reference** | +| informs **cognition** | **acquisition** of skill (study) | **explanation** | + +- *action* = doing, practical steps. *cognition* = thinking, propositional knowledge. +- *acquisition* = study/learning. *application* = getting real work done. + +Apply the compass at any zoom level: a whole topic, a section, even a sentence. When a section +"feels off," run the compass on it — usually it has drifted into a second mode. + +## The four modes at a glance + +| Mode | Serves | Question it answers | Cardinal rule | Voice | +|------|--------|---------------------|---------------|-------| +| **Tutorial** | learning by doing | "Teach me, hold my hand" | Ruthlessly minimise explanation; guarantee success | "In this tutorial *we* will…" | +| **How-to guide** | a competent user's task | "Help me get X done" | Action only; no teaching, no digression | "To achieve X, do Y." | +| **Reference** | look-up during work | "What exactly is X / its options?" | Describe and *only* describe; be austere | "The `value` property accepts a number 0–5." | +| **Explanation** | understanding a topic | "Tell me about X / why?" | Discuss, connect, weigh alternatives; stay bounded | "X exists because… An alternative is…" | + +### Tutorial — learning-oriented +A lesson. The learner learns *by doing*, under guidance, toward a meaningful, guaranteed-to-succeed +result. Show where they'll end up; deliver visible results early and often; keep a narrative of the +expected ("after a moment you'll see…"); ignore options and alternatives; minimise explanation (link +out instead). Reliability is sacred — it must work for every reader, every time. + +### How-to guide — task/goal-oriented +Directions that guide an already-competent user through a real-world problem. Defined by the *user's +goal*, not by the machinery ("How to validate a reactive form," not "The validation API"). A sequence +with flow. Omit the unnecessary; usability beats completeness. Title says exactly what it shows +("How to…"). This is a recipe, not a cooking lesson. + +### Reference — information-oriented +Neutral, authoritative technical description of the machinery — properties, methods, events, options. +Structured to mirror the code. Austere: you *consult* it, you don't read it. No instruction, no +opinion, no explanation — link out for those. Tables and examples are ideal. Best when +auto-generated from the typed source so it never drifts. + +### Explanation — understanding-oriented +Discursive treatment of a topic that permits reflection. Higher, wider view than the other three. +Answers "Can you tell me about…?" and "Why…?". Make connections, give context and history, weigh +alternatives and admit opinion. Name it with an implicit *"About …"* in front of the title. Keep it +bounded — it tends to absorb instruction and reference that belong elsewhere. + +## The two classic confusions (where writers go wrong) + +1. **Tutorial vs how-to.** Same steps, different need. A tutorial *teaches* a beginner (success + guaranteed, no choices, minimal why). A how-to serves a competent user getting a *specific job* + done (adaptable, may fork, assumes background). Don't merge them. +2. **Reference vs explanation.** Reference *describes* (cognition + work): austere, neutral, complete. + Explanation *illuminates* (cognition + study): discursive, contextual, opinionated. A properties + table is reference; "why the component works this way" is explanation. Keep them in separate + sections and link between them. + +## The golden rule + +Each unit of documentation should serve **one** need in **one** mode. When two modes want to live in +the same section, split them and cross-link. In Ignite UI topics this happens at the *section* level — +see the composite-topic principle in `SKILL.md`. diff --git a/.claude/skills/igniteui-doc-topics/references/house-style.md b/.claude/skills/igniteui-doc-topics/references/house-style.md new file mode 100644 index 0000000000..484cd57735 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/house-style.md @@ -0,0 +1,329 @@ +# Ignite UI house style + +The Ignite UI documentation conventions an authored or audited topic must follow. Pair this with +`diataxis-cheatsheet.md` (the *why*) and the section→mode map in `SKILL.md`. + +> **Current vs target state.** The live `vnext` repo is *pre-standardization* — many topics use +> drifted headings (e.g. `## Angular Rating Example`, `## Configuration`). This file describes the +> **target** standard (revision-2 blueprint). When **authoring**, write to the target. When +> **auditing**, measure against the target and report the gap. + +## Two doc sets + +| Doc set | Frameworks | Path (vnext) | Layout | One topic = | +|---|---|---|---|---| +| **Angular** | Angular only | `docs/angular/src/content/en/components/` | flat `*.mdx` | one framework | +| **xplat** | React · Web Components · Blazor | `docs/xplat/src/content/en/components//` | categorized `*.mdx` | **one file, all three frameworks** | + +The **same section list, order, and names apply to both sets.** Differences are mechanical only (see +Per-framework mechanics), never the shape of the page. **Dependencies** appears in both sets — it +covers modules to import (Angular) or supporting components/themes required to render or function +(xplat); currently seen as `## Theming Dependencies`. + +## File format & frontmatter + +Topics are **Astro `.mdx`**. Frontmatter is YAML. Observed + target fields: + +```yaml +--- +title: "Angular Star Rating Component – Ignite UI for Angular - MIT license" # SEO title +description: "…" # <=~160 chars, shaped as an answer ("X is a … that …") +keywords: "…" # comma-separated +license: MIT +mentionedTypes: ["Rating"] # xplat: API types referenced on the page +llms: + description: "…" # AI-facing one-liner; the exact text an assistant uses to summarize +relatedComponents: [Toast, Banner] # TARGET field — drives the When to Use trigger (see below) +--- +``` + +- **`llms.description`** already exists in both sets and is high-value — write it as a crisp, + self-contained answer sentence. It is *not* optional filler. +- **`relatedComponents`** is the revision-2 trigger and is **not yet in the repo**. When authoring to + target, set it. When auditing, treat a missing-but-warranted value as a finding, and a set value + with no **When to Use** section as a hard error. + +### MDX imports (declare what you use) + +```mdx +import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; # xplat only +``` + +## Per-framework mechanics + +- **Prefixes differ by framework/library — don't assume one for all:** + - **Angular** → native **`igniteui-angular`**, **`igx-`** tags / **`Igx…Component`** classes. The + Angular doc set documents this library. + - **Web Components** → **`igniteui-webcomponents`**, **`igc-`** tags / **`Igc…Component`** classes. + - **React** → **`igniteui-react`**, a **wrapper around the `igc`** web components. + - **Blazor** → **`igniteui-blazor`**, a **wrapper around the `igc`** web components. +- **Net effect:** the **xplat doc set (React / WC / Blazor) is entirely `igc`-based** — WC is `igc` + directly; React and Blazor wrap it. The **Angular doc set is `igx`**. +- **Exception — WC-first components in the Angular docs.** Some newer components are built as web + components and surfaced in the Angular docs via the `igc` element rather than a native `igx` one + (verified: the Angular **Rating** topic installs `igniteui-webcomponents`, registers + `IgcRatingComponent`, and renders ``). So **don't assume `igx` for every Angular topic** — + verify the tag/class per component. +- **Angular set:** plain prose, no platform tokens. Registers and renders whichever the component is + (`igx-…` native, or the `igc-…` WC for the exceptions above). +- **xplat set:** the *same file* serves React / WC / Blazor via: + - **Tokens** the build resolves: `{Platform}`, `{ProductName}`, `{PackageWebComponents}`, + `{PackageReact}`, `{PackageBlazor}`, etc. Use them in title/description/keywords/headings and prose + — never hard-code "React" where a token belongs. + - **`…`** to wrap framework-specific content + (install commands, imports, snippets). `for` values: `WebComponents`, `React`, `Blazor`. +- **Live samples** embed the same way in both sets: + `` +- **API links** use `` rather than hand-written URLs so they resolve per framework. + +## Never fabricate API identifiers (zero-risk rule) + +The skill's job is structure and prose, **not** to invent the API surface. Do **not** emit a guessed +tag, class, package name, property, method, event, CSS part, or theming variable. A plausible-but-wrong +name that a reader copies is worse than an obvious gap. + +- Use an identifier **only** when it is verified — from the component's typed API source, an existing + topic, or the user. The naming patterns are known (Angular `igx-` / `IgxComponent`; WC and + its React/Blazor wrappers `igc-` / `IgcComponent`), but the pattern is not a licence to + guess — confirm the exact prefix *and* `` per component (some Angular topics are `igc` — see the + exception above). +- When you must reference an unverified identifier, write a visible placeholder instead of a guess: + `‹VERIFY: exact export name›`. For a table, emit the fixed column headers and a single injection note + — invent no rows. +- This applies equally to React/Blazor wrapper symbols: they resolve to the `igc` core, so prefer the + verified `igc` usage and mark any wrapper-specific class you can't confirm with `‹VERIFY:…›`. +- **`` targets are identifiers too.** A `type` that exists in the source is not enough — it + must have a generated reference page, and the only reliable check is an existing `` with that + `type` elsewhere in the doc set. Abstract/base classes in particular (e.g. `ButtonBase`) may appear in + `mentionedTypes` yet have no page — the rendered link (e.g. `IgrButtonBase`) points nowhere. Link base-class + members through the concrete component instead (`type="Button" member="href"`), and list only the concrete + component under **API References**. + +## Component topic — canonical section order + +Required = every component topic, always this order. Conditional = only when relevant, but always in +this slot. **These names are the only allowed H2s.** Anything feature-specific becomes a sub-heading +under **Usage**, never a new top-level section. + +| # | Section (`##`) | Required? | Diátaxis mode | Contents | +|---|---|---|---|---| +| 1 | *Title + one-line definition* (`#` + lead ¶) | required | orient / reference | H1 is **`‹Component› Component`** — **no** framework prefix, **no** "Overview" suffix (the framework lives in the SEO `title`). Follow with one plain sentence: what it is, what problem it solves. Mirror `llms.description`. | +| 2 | **Overview** | required | **explanation** | Introduces the component: its primary purpose, when to reach for it, and the problems it solves, in two sub-headings — **When to Use** and **When Not to Use** (when `relatedComponents` is non-empty, name the better-fit sibling by name and link it; otherwise state the boundary generically). No install steps or API detail here. | +| 3 | *Live Demo* | required | demonstration (action) | `` of the simplest useful state, **before** any further prose. | +| 4 | **Anatomy** | conditional (recommended) | orientation (reference) | Opens with a screenshot/GIF of the component's parts or the behavior being shown, then the **DOM tree / skeleton** (rendered elements, parts, slots). If the visual asset doesn't exist yet, leave a `{/* TODO */}` marker rather than a broken image. | +| 5 | **Getting Started** | required | how-to | **Lead with the component-specific import/registration** — the page-unique, high-value part. Compress the generic library install to a **single prerequisite line linking the general getting-started topic** (an inline `ng add igniteui-angular` as a parenthetical is fine); **don't** repeat the multi-sentence install boilerplate that is identical on every component page. Show the **current** registration (standalone import) first; put legacy NgModule **after**, marked as legacy. | +| 6 | **Usage** | required | how-to | Smallest working snippet per common task; feature specifics are sub-headings here. Sub-headings name the **feature, not the component** (`Shape`, not `Avatar Shape`). Cover **every** public input; state behavioral relationships once (e.g. content-type priority) instead of repeating per option. Styling content belongs in **Styling**, not here. | +| 7 | **Best Practices** | required | **explanation** | Practical design recommendations, illustrated with correct-vs-incorrect usage (do/don't pairs). Promotes consistency, usability, and accessibility, and calls out common mistakes. Guidance and examples only — no install steps, no property tables, no accessibility-conformance detail (those stay in their own sections). | +| 8 | **Properties** | required | reference | Table: name · type · default · description. (Replaces "Configuration".) | +| 9 | **Methods** | conditional | reference | Table of callable actions. | +| 10 | **Events** | conditional | reference | Table of emitted events. | +| 11 | **Styling** | required when applicable | how-to + reference | **Open with a `` of the styled result** + one intro line, then the **Styling Variables table** (**one table** — variable · what it changes; **no default-value column, no per-theme tabs**) and styleable-parts table. Subsections cover each approach — **first `### Sass Theming`** (the primary Sass theme workflow), then others (e.g. `### Tailwind`, `### Custom sizing`). All styling content lives here, not under Usage. | +| 12 | **Accessibility** | required | reference | Three sub-sections, in order: **Keyboard Interaction** (key→action table), **Screen Readers / ARIA**, **Accessibility Compliance** (conformance evidence — see the sub-structure spec below). | +| 13 | **Troubleshooting** | conditional (required when version-migration or legacy-setup notes exist) | how-to | Gotchas phrased as the reader's real question; answer as cause → fix. **Collect version-migration notes, deprecations, and legacy/alternative approaches here** — not buried in code-fence comments or scattered asides. | +| 14 | **API References** | required | reference | `` out to the full generated reference; don't duplicate it. | +| 15 | **Dependencies** | conditional | reference | Themes, styles, or supporting components the component relies on to render or function — modules to import (Angular) or supporting components/themes (xplat). (Currently "Theming Dependencies".) | +| 16 | **Additional Resources** | required | navigation | Forums, GitHub, related topics. | + +**When Not to Use trigger:** every component topic carries **Overview** with its **When to Use / When +Not to Use** sub-headings. When `relatedComponents` is non-empty, **When Not to Use** must name the +specific better-fit sibling(s) by name and link them; when it's empty (standalone primitives like +Badge/Divider), **When Not to Use** states the boundary without inventing a sibling. (The H2 section +named **Overview** is distinct from the banned "Overview" *suffix* on the H1 title — keep the section, +drop the suffix.) + +**Reference-table contract:** Properties / Methods / Events tables are **generated from the same typed +API source** as the full reference — not hand-typed. Inline tables = the core knobs for fast scanning; +**API References** links to the complete set. One source, so nothing drifts. **When authoring, do not +hand-write or invent rows:** emit the fixed column headers (`name · type · default · description`) and a +single build-injection note, and leave the row values to the generator. Inventing a plausible property +or event name is exactly the failure this contract exists to prevent. + +**Live-sample contract:** exactly one top preview; add Usage samples only for distinct, user-facing +tasks (selection, editing, sorting, validation, templating, styling). Soft max **10 samples/page**; +up to 10 is fine, and only clear sprawl past that warrants splitting into focused topics. + +### `` configuration — pick the props deliberately + +`` renders a live demo (iframe + source-code tabs + live-edit buttons). **`src` is required and must +point at a real demo path** — treat it like any other identifier under the zero-risk rule: never invent or +guess a `src`, an `lob`/`dv`/`crm` base, or a path; use one only when it's verified from the sample project +or an existing topic, else leave a `‹VERIFY: demo path›` marker. Never hand-edit the demo's code — that lives +in the separate sample project. + +Choose the display config from **what the sample is showing**, not by habit: + +| Prop | Default | Use it when… | +|---|---|---| +| `src` | — (required) | Always. Relative demo path. | +| `alt` | — | **Always** — the iframe title for accessibility. A missing `alt` is an audit finding (E1). Describe the demo, e.g. `alt="Angular Calendar range selection"`. | +| `height` | `400` | The demo's natural height isn't ~400px. Match the content. **Mutually exclusive with `fitContent`** — set one or the other, never both. | +| `fitContent` | off | The component is small or variable-height (badge, chip, avatar, icon, switch), **or a compact standalone sub-view** (e.g. a calendar days/months/years view), and a fixed frame would waste or clip space. The iframe grows to the component's own height, so **do not also set `height`** — drop it entirely. Ignores `resizable`. | +| `iframeOnly` | off | The **result** is the point and the source isn't instructive — purely visual demos, or a Styling preview whose styling is applied upstream (not in copyable code). Drops the code tabs/footer. Keep the tabs when the code *is* the lesson (e.g. a Sass `calendar-theme` snippet). | +| `fullscreenBtn` | off | Paired with `iframeOnly` for large/complex visual demos that benefit from full-screen. | +| `resizable` | off | Responsiveness is the lesson (grids, layout, splitter, dock manager) — lets the reader drag the width. Ignored with `fitContent`. | +| `position` | — | A small component would otherwise sit in the top-left; align it (`center`, etc.). | +| `spacing` | — | The demo needs breathing room around the iframe (`sm`/`md`/`lg` = 8/16/32px). | +| `noBorder` | off | The default border competes with the demo visually. Cosmetic — use sparingly. | +| `lob` / `dv` / `crm` | default base | The demo lives in the LOB, Data-Viz, or CRM demos app rather than the default — **verify before setting**. | + +Defaults are right for most Usage samples: ``. Reach for the extra props +only when the component type calls for it — the top preview and standard task demos keep the code tabs (no +`iframeOnly`); the **Styling** section still opens with a styled-result ``, using `iframeOnly` only +when its styling isn't shown as copyable code. + +### Accessibility — required sub-structure + +`## Accessibility` always carries three `###` sub-sections, in this order. All three are **reference** +mode: statements of fact in tables and short lists — no steps, no marketing. + +1. **`### Keyboard Interaction`** — one key → action table, verified against the component's key + handlers. Note how the component is reached (Tab) and any condition that removes it from the tab + order. +2. **`### Screen Readers / ARIA`** — the roles, `aria-*` attributes, and announcements the component + provides (from source), plus what the reader must supply (e.g. `aria-label` when the visible + content doesn't describe the action). +3. **`### Accessibility Compliance`** — the conformance evidence, in this shape: + - **Lead sentence** naming the conformance target (WCAG version + level; Section 508 / EN 301 549 + where applicable). This is a product-level claim — state it only from an official Infragistics + statement; otherwise write `‹VERIFY: conformance target›`. + - **Conformance table** — two columns: **Criterion · How the component complies**. List only the + WCAG success criteria *relevant to this component*, each row grounded in behavior already + verified on this page (the keyboard table, the ARIA facts, the typed source). Link each + criterion to its WCAG Understanding page. Common criteria to pick from: + 1.3.1 Info and Relationships (roles/structure) · 1.4.1 Use of Color (states not conveyed by + color alone) · 1.4.3 Contrast (Minimum) (default themes) · 1.4.11 Non-text Contrast · + 2.1.1 Keyboard + 2.1.2 No Keyboard Trap (full keyboard operability) · 2.4.3 Focus Order · + 2.4.7 Focus Visible (focus ring) · 2.5.7 Dragging Movements (every drag interaction needs a + keyboard/single-pointer alternative — splitter, slider, dock manager) · 2.5.8 Target Size + (Minimum) · 4.1.2 Name, Role, Value · 4.1.3 Status Messages (components that announce — toast, + snackbar, progress). Omit irrelevant criteria entirely — no "N/A" filler rows. + - **Your responsibilities** — a short list of what the app author must still do for the page to + conform: provide the accessible name, keep sufficient contrast when overriding themes, preserve + a logical focus order in the surrounding layout, keep minimum target sizes when custom-sizing. + Cross-link the Usage/Styling sections that show *how* — don't repeat the steps here. This split + (what the component guarantees vs what the reader owes) is the highest-value content of the + sub-section for both humans and AI assistants. + - **Known exceptions** *(only when real)* — criteria the component doesn't fully meet, each with + its workaround or tracking link. An honest, specific gap beats a silent one. + - **Validation & resources** *(optional, verified only)* — the screen reader / AT combinations the + component is tested with, and links to the product accessibility statement / VPAT and the + matching [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) pattern. + Omit when unverified — never invent a testing matrix. + + Compliance claims are the highest-risk statements on the page — they carry legal weight, and a + wrong one is copied into the reader's own conformance report. The zero-risk rule applies at full + strength: no blanket "fully accessible" / "WCAG compliant" sentence, ever; every table row traces + to observable, verified behavior; product-level claims come only from an official source. + +## Overview topics + +**5a. Concept / guide overview** (Diátaxis: *explanation*) — e.g. "Theming concepts": +Title + intro → **What You'll Learn** (roadmap) → Concept sections → *Key Capabilities* (cond.) → +*When to Use / When Not to Use* (cond.) → **Next Steps** → **API References / Additional Resources**. + +**5b. Category / index overview** (Diátaxis: *reference/navigation* — a map) — e.g. "Charts overview": +Title + intro → **Types / Members** (identical micro-structure per entry: one-line def + link + small +``) → *Key Features* (cond.) → **Next Steps / API References / Additional Resources**. + +Guardrails: cap each section at ~3 short paragraphs (else add sub-sections); isolate marketing copy in +a single "Why {ProductName}" section — never thread it through instructional content. + +## Naming reconciliation (drift → standard) + +| Seen in the wild | Standard name | +|---|---| +| "Angular X Component Overview"; "X Component Overview"; "{Platform} X Component Overview" (H1) | **`X Component`** (H1 — drop framework + "Overview") | +| Setup; "Getting Started with…"; "Getting Started with Ignite UI for Angular X" | **Getting Started** | +| Code Snippet; Examples; "Using the … Component"; "{Platform} X Example"; "Angular X Example" | **Usage** | +| "Avatar Shape"; "‹Component› ‹Feature›" (Usage sub-heading) | **`‹Feature›`** (drop the component name) | +| Configuration | **Properties** | +| "X vs Y"; "Choosing Between X and Y"; Behavior; Feature Integration | **When to Use** (as `###` under **Overview**) | +| top-level `## When to Use` / `## When Not to Use`; **When to Use / When Not to Use nested under `## Anatomy`** | **`### When to Use` / `### When Not to Use`** nested under **`## Overview`** (first section, before Live Demo) | +| Summary (as lead-in) | intro ¶ or **What You'll Learn** | +| Keyboard Navigation | **Accessibility** | +| WAI-ARIA Support; Compliance; Section 508; Accessibility Statement | **`### Accessibility Compliance`** (under **Accessibility**) | +| Do's and Don'ts; Guidelines; Recommendations | **Best Practices** | +| Theming (H2) | **Styling** (H2); the Sass approach becomes `### Sass Theming` under it | +| Known Limitations; Known Issues and Limitations; Limitations | **Troubleshooting** | +| API; API Reference (singular) | **API References** | +| Theming Dependencies | **Dependencies** | + +## Write-for-both-audiences rules (people + AI assistants) + +1. **One job per section** — self-contained; no "as mentioned above." A section must make sense landed-on cold. +2. **Lead each section with one plain, specific sentence** before any table/code — skip empty boilerplate. +3. **Use the standard section names everywhere** — "Accessibility" always means the same thing. +4. **Phrase guidance/troubleshooting as real questions** — When-Not-to-Use is the highest-value content for answer accuracy; name the sibling explicitly. +5. **Reference lives in tables**, generated from the typed source. +6. **Strong `description` / `llms.description`** — <~160 chars, answer-shaped. +7. **Document theming variables** — variable · what it changes, in **one table for all themes**. No default-value column: defaults are per-theme values that live in the generated API reference, not the topic. + +## Formatting & altitude + +- **No divider hugging a block.** Never place `
` or `` directly before or after a + ``, code fence, or table — those blocks carry their own separation. Dividers separate + *prose* sections only; in practice a topic rarely needs them at all. +- **Single item ⇒ paragraph.** A `ul`/`ol` with one item is a paragraph. Use a list only for two or + more parallel items. +- **Current API first, legacy after.** Show the current/recommended approach first (e.g. the + standalone component import); place deprecated/legacy approaches (NgModule) *below* it, explicitly + marked as legacy — never above the current one. +- **Don't repeat the generic install boilerplate.** The `ng add igniteui-angular` + "read the getting + started topic" prose is identical on every component page — collapse it to a **one-line prerequisite + link** and lead Getting Started with the component-specific import instead. This mirrors how the major + component libraries (Angular Material, MUI, Ant Design, PrimeNG) work: install lives in one central + page; each component page shows only its own import. Keep the prerequisite as a single linked line + (optionally with an inline `ng add` token) so a cold-landing reader or AI still has the pointer — just + not the repeated paragraph. +- **Styling leads with the result.** The Styling section opens with a `` of the styled + outcome, then the tables; its first subsection is `### Sass Theming` (the Sass theme workflow), then + the other approaches (`### Tailwind`, `### Custom sizing`, …). +- **One styling table — never per-theme tabs, never default values.** In the `theming` repo every + theme schema `extend`s the same base schema and only overrides *values* (e.g. `$material-switch`, + `$fluent-switch`, `$indigo-switch` all extend `$light-switch`; `$bootstrap-switch` extends + `$fluent-switch`), so **every theme exposes the identical variable set** — only the defaults differ. + Per-theme tabbed tables (the legacy `.theme-switcher-wrapper` / `.theme-table` markup) therefore + document a difference that doesn't exist; replace them with **one two-column table: + variable · what it changes**. Don't add a defaults column either — defaults vary per theme and + belong to the generated API reference, and the durable content is the variable's name and effect. +- **Audit & modernize inline code snippets — not the samples.** Fenced code blocks (` ```… ``` + `) are authored in the topic, so verify and update them: no deprecated APIs or outdated framework + idioms (drop `standalone: true`; prefer Angular's built-in control flow `@if`/`@for` over + `*ngIf`/`*ngFor`; use verified imports, selectors, and tags). The live **``** embeds render + from the separate sample project — **never hand-edit their code**; fix those upstream. The only + intentionally "old" snippets are the legacy ones quarantined in **Troubleshooting**. +- **Omit `standalone: true` (Angular).** Components are standalone by default since Angular v19 + (igniteui-angular targets far newer), so it's redundant in examples — don't write it. Show + `standalone: false` only when illustrating the legacy NgModule path (in Troubleshooting). +- **Version & legacy notes live in Troubleshooting.** Don't bury "prior to vX use…" migration notes + in code-fence comments, and don't scatter legacy/alternative setup (e.g. NgModule) across the page. + Collect them in **Troubleshooting**, each phrased as question → cause → fix. Getting Started and + code samples show only the current, recommended path. +- **Curated (not generated) reference tables — for now.** No build-time generator injects inline + Properties/Styling-Variables tables yet (only the full API reference is generated, reached via + ``). Until one exists, hand-author a **small core** table whose every row is **verified + from source** (typed component for props; the `@param` doc-comments in the component's + `_…-theme.scss` for styling vars) and link `` for the complete set. The zero-risk rule + still applies: no unverified rows. + +## Voice & tone + +Write instructions the same way across every topic so readers (and assistants) get one predictable voice. + +- **Imperative, second person, present tense.** "Set the `shape` attribute…", "Import the component…" — not "we create…" or "the developer should…". Address the reader as *you* only when needed for clarity. +- **One voice per topic.** Don't mix imperative how-to with first-person-plural narration ("we create") or tutorial hand-holding. Reference sections (Properties/Styling tables, Accessibility) stay descriptive. +- **Specific over vague; cut filler.** Name the exact attribute, value, or behavior. Drop "simply", "just", "in order to", "as you can see", and empty lead-ins. +- **No marketing in instructional prose.** Keep promotion out of how-to/reference; overview topics isolate it in a single "Why {ProductName}" slot. +- **Name features by their real Ignite UI identifier** (e.g. `igx-icon`, not "material icon") and cross-link the topic. + +## Verify every claim against the component + +The zero-risk rule is not limited to identifiers — **every statement of fact must be verified against the actual component before it ships or is recommended as an edit.** This includes defaults, value ranges, precedence/fallback behavior, version support ("since vX"), deprecations, emitted events, and rendered DOM. + +- **Source of truth, in order:** the component's typed source (inputs, `@HostBinding`, template, theme `.scss` `@param` comments) → the official generated API docs → an existing verified topic → the user. For framework-version behavior (e.g. Angular standalone defaults), check the **official framework docs**, not memory. +- **When recommending edits, verify first.** Never "correct" prose into a plausible-sounding claim you haven't checked — a confident wrong statement is worse than the original. +- **If you can't verify it, don't assert it.** Write `‹VERIFY: …›` or leave the existing text and flag it — never guess a default, a version, or a behavior. +- Behavioral claims that read fine but contradict the source (e.g. "the image falls back to initials on load error" when the code only sets precedence) are exactly what this rule catches. From aa578b86c838948431bde5e0ff55d6f81d031aff Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 9 Jul 2026 11:36:48 +0300 Subject: [PATCH 2/8] fix(docs): Update Angular Avatar,calendar documentation using the new skill. --- .../src/content/en/components/avatar.mdx | 306 ++++--- .../src/content/en/components/calendar.mdx | 819 ++++++++---------- 2 files changed, 552 insertions(+), 573 deletions(-) diff --git a/docs/angular/src/content/en/components/avatar.mdx b/docs/angular/src/content/en/components/avatar.mdx index ed90d5299c..f2921cde8f 100644 --- a/docs/angular/src/content/en/components/avatar.mdx +++ b/docs/angular/src/content/en/components/avatar.mdx @@ -1,215 +1,214 @@ --- title: Angular Avatar Component – Ignite UI for Angular | Infragistics | MIT license -description: Ignite UI for Angular Avatar control enables users to add images, material icons or initials within any application for instances such as a profile button. +description: The Ignite UI for Angular Avatar is a compact UI element that represents a user or entity with a profile image, an igx-icon, or their initials. keywords: Angular Avatar component, Angular Avatar control, Ignite UI for Angular, Angular UI components license: MIT llms: - description: "Angular Avatar component helps adding initials, images, or material icons to your application." + description: "The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an igx-icon, or their initials." +relatedComponents: [Badge] --- 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 Avatar Component Overview +# Avatar Component
-Angular Avatar component helps adding initials, images, or material icons to your application. +The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an `igx-icon`, or their initials.
- -## Angular Avatar Example +## Overview - +### When to Use -
+Use the avatar to represent a user, entity, or object with a compact image, icon, or set of initials — for example a profile button, a comment author, or a list item's leading visual. -## Getting Started with Ignite UI for Angular Avatar +### When Not to Use -To get started with the Ignite UI for Angular Avatar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: +To display a count, status, or notification indicator rather than represent an entity, use the component, which is designed to decorate other elements (including avatars) with a small count or status icon. -```cmd -ng add igniteui-angular -``` + -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. +## Anatomy -The next step is to import the `IgxAvatarModule` in your **app.module.ts** file. +{/* TODO: add an anatomy diagram (screenshot or GIF) labeling the avatar's parts. */} -```typescript -// app.module.ts +The avatar is a single host element that renders one content template, chosen by [content priority](#content). Its rendered DOM is: -... -import { IgxAvatarModule } from 'igniteui-angular/avatar'; -// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxAvatarModule], - ... -}) -export class AppModule {} +``` +igx-avatar[role="img"] // host — shape & size set via attributes / CSS vars +└─ one of, by priority: + ├─ div.igx-avatar__image // `src` set — image painted as a background + ├─ igx-icon // `icon` set + ├─ span // `initials` set — first two characters + └─ // custom projected content ``` -Alternatively, as of `16.0.0` you can import the `IgxAvatarComponent` as a standalone dependency. +## Getting Started + +Install Ignite UI for Angular first (`ng add igniteui-angular`) — see [Getting Started](/general/getting-started) for the full walkthrough. + +Import the standalone `IgxAvatarComponent` and add it to your component's `imports` array, then use the `` tag in that component's template. ```typescript // home.component.ts - -... +import { Component } from '@angular/core'; import { IgxAvatarComponent } from 'igniteui-angular/avatar'; -// import { IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package +// Licensed package: import from '@infragistics/igniteui-angular' instead @Component({ selector: 'app-home', - template: '', - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IgxAvatarComponent] + imports: [IgxAvatarComponent], // makes available in this template + template: '' }) export class HomeComponent {} ``` -Now that you have the Ignite UI for Angular Avatar module or component imported, you can start with a basic configuration of the `igx-avatar` component. - -## Using the Angular Avatar Component +## Usage -The Ignite UI for Angular Avatar component comes in three shapes (square, rounded, and circle) and three size options (small, medium, and large). It can be used for displaying initials, images or icons. +The avatar renders initials, an image, or an [`igx-icon`](/icon), in one of three shapes and three preset sizes. -### Avatar Shape +### Shape -We can change the avatar shape through the `shape` attribute setting its value to `square`, `rounded` or `circle`. By default, the shape of the avatar is `square`. +Set the `shape` attribute to `square`, `rounded`, or `circle`. The default is `square`. ```html ``` -### Avatar displaying initials +### Size -To get a simple avatar with (i.e. JS for 'Jack Sock'), add the following code inside the component template: +Set the `size` attribute to a preset value — `small`, `medium`, or `large` (default `small`). For arbitrary sizes, use the CSS variables described under [Custom sizing](#custom-sizing). ```html - + ``` -Let's enhance our avatar by making it circular and bigger in size. +### Content -```html - -``` +An avatar displays a single kind of content, chosen by **priority**: (image) wins over , which wins over . Set the one you need — a higher-priority value hides the others (this is a precedence rule, not an image load-failure fallback). If none is set, the avatar renders its projected content. -We can also change the background using the `--ig-avatar-background` CSS variable or set a color on the initials through the `color` property. - -```scss -// avatar.component.scss - -igx-avatar { - --ig-avatar-background: #e41c77; - color: #000000; -} +**Initials** — the first two characters of `initials` are shown (e.g. `JS` for "Jack Sock"): +```html + ``` - -The `roundShape` property of the `igx-avatar` component have been deprecated. The `shape` attribute should be used instead. - + -If all went well, you should see something like the following in the browser: +**Image** — set the image URL via `src`: - +```html + +``` -### Avatar displaying image + -To get an avatar that displays an image, all you have to do is set the image source via the `src` property. +**Icon** — render an [`igx-icon`](/icon) by setting its name via `icon`: ```html - - + ``` + +The avatar renders icons with the [`igx-icon`](/icon) component. To use Google's Material Icons font, add the following to your `index.html`: `` + -If all went well, you should see something like the following in the browser: + - +## Best Practices -### Avatar displaying icon +- Pick one content strategy per context and use it consistently — mixing images, icons, and initials in the same list of avatars reads as inconsistent. +- Set only the content you intend to show. `src`, `icon`, and `initials` follow a fixed precedence rather than falling back automatically on failure, so an unreachable image URL won't be replaced by initials — verify the URL if you need a reliable result. +- Set a descriptive `aria-label` whenever the avatar identifies a specific person or entity, not just when it's convenient. +- Don't use the avatar to show a count, status, or notification badge — decorate it with instead of encoding that information into the initials or icon. -Analogically, the avatar can display an icon via the property. Currently all icons from the material icon set are supported. +## Properties -```html - - -``` +The core inputs used to configure the avatar are listed below. For the complete, always-current API surface, see the [API References](#api-references) section. - -This component uses Material Icons. Add the following link to your `index.html`: `` - +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `shape` | `"square" \| "rounded" \| "circle"` | `"square"` | Sets the shape of the avatar. | +| `size` | `"small" \| "medium" \| "large"` | `"small"` | Sets the size of the avatar. | +| `initials` | `string` | — | Text initials rendered when no image or icon is set. | +| `icon` | `string` | — | Icon name to render via [`igx-icon`](/icon). | +| `src` | `string` | — | Image source URL to render. | +| `id` | `string` | `"igx-avatar-{n}"` | The unique identifier of the avatar. | -You should see something like this: +## Styling - + -## Styling +The avatar's appearance is controlled through the parameters below. Set `$background`, and the contrast-dependent colors (`$color` and `$icon-color`) are derived automatically. -### Avatar Theme Property Map +| Variable | Description | +| --- | --- | +| `$background` | The avatar background color. Primary token — derives `$color` and `$icon-color`. | +| `$color` | The text/initials color. Auto-derived from `$background` for contrast when not set. | +| `$icon-color` | The icon color. Auto-derived from `$background` for contrast when not set. | +| `$border-radius` | The border radius. Only takes effect when `shape` is `rounded`. | +| `$size` | The size of the avatar. | -Changing the `$background` property automatically updates the following dependent properties: +### Sass Theming -| Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$background** | $color | The text color used for the avatar. | -| | $icon-color | The icon color used for the avatar. | +#### Using SCSS -To get started with styling the avatar, we need to import the `index` file, where all the theme functions and component mixins live: +To get started with styling the avatar, import the theme entry point 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 providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that the `$border-radius` property only takes effect when the avatar's `shape` is set to `rounded`. +Create a new theme that extends the , providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that `$border-radius` only takes effect when the avatar's `shape` is set to `rounded`. Given the following markup: ```html -
- - +
+
``` -We create the following avatar theme: +Create the theme: ```scss $custom-avatar-theme: avatar-theme( - $background: #72da67, - $border-radius: 16px + $background: #72da67, + $border-radius: 16px ); ``` -The last step is to pass the custom avatar theme: +Then apply it to your markup: ```scss -.initials { - @include tokens($custom-avatar-theme); +.my-container:has(igx-avatar[initials]) { + @include tokens($custom-avatar-theme); } ``` -If all went well, you should see something like the following in the browser: +#### Using pure CSS - +Prefer not to use SCSS? Override the component's CSS variables directly: -### Styling with Tailwind +```css +/* overrides all avatars */ +:root { + --ig-avatar-background: #e41c77; +} -You can style the `avatar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. +/* overrides only the avatar with class .special */ +igx-avatar.special { + --background: #e41c77; +} +``` + +### Tailwind + +You can style the avatar using our 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: +With the Tailwind import in your global stylesheet, apply the theme utilities: ```scss @import "tailwindcss"; @@ -223,25 +222,23 @@ The utility file includes both `light` and `dark` theme variants. - Use `dark-*` classes for the dark theme. - Append the component name after the prefix, e.g., `light-avatar`, `dark-avatar`. -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.). +Once applied, these classes enable dynamic theme calculations. From there, override the generated CSS variables using Tailwind's arbitrary-property syntax — for example `[--background:#FF4E00]` — with 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: +See the for the full list of parameters. For example: ```html + class="!light-avatar ![--background:#FF4E00]" + initials="DY" + shape="rounded"> ``` -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. +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 avatar should look like this: - - + ### Custom sizing @@ -257,7 +254,6 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances ```html
-
``` @@ -268,7 +264,7 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances } ``` -You can also use one of the predefined sizes, assigning it to the `--ig-size` variable, if theres no size attribute applied. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: +You can also use one of the predefined sizes by assigning it to the `--ig-size` variable, if no `size` attribute is set. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: ```scss igx-avatar { @@ -276,22 +272,80 @@ igx-avatar { } ``` -Learn more about it in the [Size](/display-density) article. +Learn more in the [Size](/display-density) article. + +## Accessibility + +### Keyboard Interaction + +The avatar is a non-interactive, presentational element — it doesn't receive focus and has no keyboard interaction to document. + +### Screen Readers / ARIA + +The avatar renders with `role="img"` and a default `aria-label` of `avatar`, and it automatically sets `aria-roledescription` to reflect its content — `image avatar`, `icon avatar`, `initials avatar`, or `custom avatar` for projected content. + +When the avatar carries meaning — such as identifying a specific person — set a descriptive `aria-label` so screen-reader users get the same information sighted users get from the image, icon, or initials: + +```html + +``` + +If the avatar is purely decorative and its meaning is already conveyed by adjacent text (for example, a name shown next to it), keep the label minimal so the same information isn't announced twice. + +### Accessibility Compliance + +Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. + +| Criterion | How the Avatar complies | +| --- | --- | +| [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) | The default `aria-label="avatar"` gives every avatar an accessible name; set your own `aria-label` when the image, icon, or initials convey specific meaning (e.g. a person's identity). | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The host element exposes `role="img"` and an `aria-roledescription` (`image avatar`, `icon avatar`, `initials avatar`, or `custom avatar`) reflecting its current content. | + +**Your responsibilities** + +- Provide a descriptive `aria-label` whenever the avatar identifies a specific person or entity. +- Keep sufficient color contrast between the avatar's background and its text/icon color when customizing the theme — see [Styling](#styling). + +## Troubleshooting + +### Why doesn't the `roundShape` property work anymore? + +`roundShape` was replaced by `shape` in `15.1.0`. Run `ng update` to migrate existing usages automatically, or update them by hand — `shape="circle"` replaces `roundShape="true"`, and `shape="square"` (the default) replaces `roundShape="false"`. + +### How do I use the avatar in a module-based (NgModule) app? + +Standalone is the default in modern Angular, and Ignite UI for Angular components support it since `16.0.0`. In an older, module-based application, import `IgxAvatarModule` and add it to your `@NgModule` `imports` array instead of importing the component directly: + +```typescript +// app.module.ts +import { IgxAvatarModule } from 'igniteui-angular/avatar'; +// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + imports: [IgxAvatarModule], +}) +export class AppModule {} +``` + +### Why does my theme import fail on older versions? + +The `@use "igniteui-angular/theming" as *;` entry point was introduced in v13. On earlier versions, import the themes index instead: -
+```scss +@import '~igniteui-angular/lib/core/styles/themes/index'; +``` ## API References -
+ - -## Theming Dependencies + +## 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) diff --git a/docs/angular/src/content/en/components/calendar.mdx b/docs/angular/src/content/en/components/calendar.mdx index 0a61a83248..7c64935b01 100644 --- a/docs/angular/src/content/en/components/calendar.mdx +++ b/docs/angular/src/content/en/components/calendar.mdx @@ -1,8 +1,9 @@ --- -title: Angular Calendar Component – Ignite UI for Angular | MIT license -description: With Angular Calendar Component, users can create intuitive calendars for applications to display date information using three different selection modes. Try it Now +title: Angular Calendar Component – Ignite UI for Angular | MIT license +description: The Angular Calendar component displays dates with single, multiple, or range selection, localization, disabled and special dates, and multiple views. keywords: angular calendar, angular calendar component, angular UI components, angular UI library, ignite ui for angular license: MIT +relatedComponents: [DatePicker, DateRangePicker] llms: description: "Angular Calendar is a UI component used for displaying dates and days in an app." --- @@ -11,59 +12,47 @@ 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 Calendar Component Overview +# Calendar Component -Angular Calendar is a UI component used for displaying dates and days in an app. Supporting different features, it enables users to easily manage calendar functionalities, drag and create events in a calendar, navigate to a preferred date in it, and show events in an Angular calendar month view, week view, or day view in a single click. +Angular Calendar is a UI component used for displaying dates and days in an app. It renders a month, year, or decade view and lets users select a single date, multiple dates, or a date range, with support for localization, disabled dates, and special dates. -
+## Overview -The Ignite UI for Angular Calendar component, developed as a native [Angular component](https://angular.io/guide/architecture#components), provides an easy and intuitive ways to display date information, enable dates or apply Angular calendar disable dates mode. Users can choose from three different selection modes - single selection, multi selection or range selection. -
+### When to Use -## Angular Calendar Example +Use the Calendar when you need an always-visible date surface embedded in the page — a scheduling panel, an availability view, or a form that benefits from selecting single dates, multiple dates, or a range directly in the layout. -We created the following Angular Calendar example using the Ignite UI for Angular Calendar package. It quickly shows how a basic calendar looks and feels like, how users can choose and highlight a single date, and how to move back and forth to a specific date. +### When Not to Use -
+- To bind a single date to a text input in a compact dropdown, use the — it hosts a calendar in a drop-down and exposes the value through an input. +- To capture a start/end pair bound to inputs, use the instead of wiring range selection onto a bare calendar. - + -## Getting Started with Ignite UI for Angular Calendar +## Anatomy -To get started with the Ignite UI for Angular Calendar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: +{/* TODO: add an annotated screenshot of the calendar parts (header, navigation subheader, days grid). */} -```cmd -ng add igniteui-angular +The calendar renders a header, a navigation subheader, and a view area that swaps between the days, months, and years views. The header is hidden when `selection` is `multi` or `range`. + +``` +igx-calendar +├── Header // selected date; hidden for multi/range selection +├── Navigation subheader // previous button · month button · year button · next button +└── View area (role="grid") + ├── igx-days-view // day grid for the current month(s) + ├── igx-months-view // month picker + └── igx-years-view // decade (year) picker ``` -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. +## Getting Started -The next step is to import the `IgxCalendarModule` in your **app.module.ts** file. +Requires Ignite UI for Angular — see [Getting Started](/general/getting-started) (`ng add igniteui-angular`). - -The also depends on the [`BrowserAnimationsModule`](https://angular.io/api/platform-browser/animations/BrowserAnimationsModule), so it needs to be added to the AppModule as well: - - -```typescript -// app.module.ts -... -import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; -import { IgxCalendarModule } from 'igniteui-angular/calendar'; -// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., BrowserAnimationsModule, IgxCalendarModule], - ... -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxCalendarComponent` as a standalone dependency, or use the [`IGX_CALENDAR_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/calendar/src/calendar/public_api.ts) token to import the component and all of its supporting components and directives. +Import `IGX_CALENDAR_DIRECTIVES` in the component where you use the calendar. The calendar also depends on `BrowserAnimationsModule`, so add it to the same `imports`: ```typescript // home.component.ts - import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; // import { IGX_CALENDAR_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package @@ -72,72 +61,66 @@ import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; selector: 'app-home', template: '', styleUrls: ['home.component.scss'], - standalone: true, imports: [BrowserAnimationsModule, IGX_CALENDAR_DIRECTIVES] - /* or imports: [BrowserAnimationsModule, IgxCalendarComponent] */ }) export class HomeComponent {} ``` -Now that you have the Ignite UI for Angular Calendar module or directives imported, you can start using the `igx-calendar` component. +The `IGX_CALENDAR_DIRECTIVES` token imports the together with its views and supporting directives. To register the calendar on its own, import `IgxCalendarComponent` instead. For the legacy `NgModule` setup, see [Troubleshooting](#troubleshooting). -The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. +The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. -Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. -## Using the Angular Calendar +## Usage -### Angular Single Selection Calendar +### Single selection -Instantiating the `IgxCalendarComponent` is as easy as placing its selector element in the template. This will display the current month in the single selection calendar mode. +Place the `igx-calendar` selector in the template. With no `selection` set, the calendar renders the current month in single selection mode: ```html {/* app.component.html */} -{/* Single selection mode */} ``` -### Angular Calendar Multiselect +### Multiple selection -We can easily change the default mode using the property: +Set the property to `multi` to let users pick several individual dates: ```html {/* app.component.html */} -{/* Multi selection mode */} ``` - + -### Angular Calendar Range Picker +### Range selection -Following the same approach, we can switch to range selection mode: +Set `selection` to `range` to let users pick a continuous range between two dates: ```html {/* app.component.html */} -{/* Range selection mode */} ``` - + -Notice that the calendar header is not rendered when the selection is either `multi` or `range`. +The calendar header is not rendered when `selection` is either `multi` or `range`. -### Localization and Formatting +### Localization and formatting -Due to their very nature, localization and formatting are essential to any calendar. In the `IgxCalendarComponent` those are controlled and customized through the following properties - , , , . +Control localization and formatting through , , , and . -Let's go ahead and try those along with other customizations from the `IgxCalendarComponent API`. First thing we need to set is the `weekStart`, which controls the starting day of the week. It defaults to 0, which corresponds to Sunday, so we will set a value of 1 for Monday. In the markup below we are also binding the `formatOptions` and `formatViews` properties to customize the display formatting. Finally, we are binding the `locale` property to a value, based on the user's location choice: +`weekStart` sets the starting day of the week. If you don't set it, the calendar uses the first day of the week for its `locale`. Set it to `1` for Monday. `formatOptions` and `formatViews` customize how the day, month, and year are rendered, and `locale` sets the language: ```html {/* app.component.html */} - - {{ locale }} - + @for (locale of locales; track locale) { + {{ locale }} + } ``` -All property values should be set in the AppComponent file: +Set the bound values in the component: ```typescript // app.component.ts @@ -165,17 +148,13 @@ public ngOnInit() { } ``` -If everything went well, we should now have a calendar with customized dates display, that also changes the locale representation, based on the user location. Let's have a look at it: - - + -### How to Disable Dates In Angular Calendar +### Disabled dates -This section demonstrates the usage of functionality. For this purpose, different single dates or ranges can be added to an array and then passed to the `disabledDates` descriptor. +Assign an array of descriptors to to prevent dates from being selected. Use to describe the range to disable. -The is used to specify a range that is going to be disabled. - -Let's create a sample that is disabling the dates between the 3rd and the 8th of the current month: +Disable the dates between the 3rd and the 8th of the current month: ```typescript export class CalendarSample6Component { @@ -192,15 +171,11 @@ export class CalendarSample6Component { } ``` -These configurations should have the following result: - - + ### Special dates -The feature is using almost the same configuration principles as the `disabledDates`. The ability to select and focus `specialDates` is what differs them from the `disabled` ones. - -Let's add some `specialDates` to our `igxCalendar`. In order to do this, we have to create a item of type and pass an array of dates as a : + uses the same descriptor configuration as `disabledDates`, but special dates stay selectable and focusable. Create a of type and pass an array of dates as its : ```typescript export class CalendarSample7Component { @@ -239,165 +214,44 @@ export class CalendarSample7Component { ``` -The following demo illustrates a calendar with a vacation request option: - - + ### Week numbers -You can now use input to show the week numbers for both Calendar and DatePicker components. +Set to `true` to display week numbers. The same input applies to the Date Picker. ```html - {/* app.component.html */} ``` -The following demo illustrates a calendar with enabled week numbers: - - - -## Calendar Events - -Let's explore the events emitted by the calendar: - -- - emitted when selecting date(s) in the calendar. -- - emitted every time when the presented month/year is changed - for example after navigating to the `next` or `previous` month. -- - emitted after the active view is changed - for example after the user has clicked on the `month` or `year` section in the header. - -```html -{/* app.component.html */} - - -``` - -The event is suitable to build input validation logic. Use the code from below to alert the user if selection exceeds 5 days, and then reset the selection: - -```typescript -// app.component.ts -... -public onSelection(dates: Date[]) { - if (dates.length > 5) { - this.calendar.selectedDates = []; - // alert the user - } -} -public viewDateChanged(event: IViewDateChangeEventArgs) { - // use event.previousValue to get previous month/year that was presented. - // use event.currentValue to get current month/year that is presented. -} - -public activeViewChanged(event: CalendarView) { - // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE) -} -``` - -Use the demo below to play around (change selection, navigate through months and years) and see the events logged real time: - - - -## Angular Calendar Views - -There are separate views provided by the `IgxCalendarModule` that can be used independently: - -- Angular Calendar Days View - - - + -- Angular Calendar Month View - +### Views - +The days, months, and years views ship as standalone components you can use independently of the full calendar: -- Angular Calendar Year View - +- — the day grid. - + -## Keyboard navigation +- — the month picker. -If you traverse the page using _Tab key_ you should keep in mind that based on [W3 accessibility recommendations](https://www.w3.org/TR/wai-aria-practices/#layoutGrid) the _igxCalendarComponent_ now introduces the following tab stops: + -- Previous month button -- Month selection button -- Year selection button -- Next month button -- Selected date, Current date, First focusable (not disabled) date in the days view - -In an Angular Calendar that contains more than one selected dates, only the first date will be introduced as a tab stop. For example, when an Angular Calendar multi-select is enabled and you have selected the dates: _13/10/2020_, _17/10/2020_ and _21/10/2020_ only _13/10/2020_ will be accessible during tab navigation; in an Angular Calendar Range Picker, only the first date of the selected range will be part of the _page tab sequence_. - - -Behavioral change, from _v10.2.0_ - Tab key navigation in the _days view_ is no longer available. In order to navigate between the dates in the _date view_ you should use the _arrow keys_. - - -When the `igxCalendar` component is focused, use: - -- PageUp key to move to the previous month, -- PageDown key to move to the next month, -- Shift + PageUp keys to move to the previous year, -- Shift + PageDown keys to move to the next year, -- Home key to focus the first day of the current month or first month in view -- End key to focus the last day of the current month or last month in view - -When the `prev` or the `next` month buttons (in the subheader) are focused, use: - -- Space or Enter key to scroll into view the next or previous month. - -When the `months` button (in the subheader) is focused, use: - -- Space or Enter key to open the months view. - -When the `year` button (in the subheader) is focused, use: - -- Space or Enter key to open the decade view. - -When a `day` inside the current month is focused: - -- Use _Arrow keys_ to navigate through the days. Note: The disabled dates will be skipped. -- Focus will be persisted on the current month that is in the view, while navigation **from**/**to** the **last day**/**first day** of the month. -- THe kb navigation would be continuous, which means that it will go through all months while navigating with the arrows. -- Use Enter key to select the currently focused day. - -When a `month` inside the months view is focused, use: - -- Arrow keys to navigate through the months. -- Home key to focus the first month inside the months view. -- End key to focus the last month inside the months view. -- Enter key to select the currently focused month and close the view. - -When an `year` inside the decade view is focused, use: - -- Arrow up and Arrow down keys to navigate through the years, -- Enter key to select the currently focused year and close the view. - - -Following version 8.2.0, keyboard navigation will not focus days that are outside of current month, but will rather change the month in view. - +- — the year picker. -## Multi View Calendar + -Multi-view calendar supports all three types of selection. Use the input to set the number of displayed months, which will be shown horizontally in a flex container. There is no limit on the max value set. While using a multi view calendar, you may want to hide the days that do not belong to the current month. You are able to do it with the property. Keyboard navigation moves to next/previous months when those are in view. +### Multi-view - +Set to render several months side by side in a flex container; multi-view supports all three selection types. There is no maximum value. Set to `true` to hide days that don't belong to the current month, and keyboard navigation moves to the next or previous month when it is in view. -## Calendar Orientation + -The orientation settings allows users to choose how the header and the view of the calendar are displayed. +### Orientation -### Header Orientation Options - -You can change the header orientation to place the header of the calendar to be either horizontal(above the calendar view) or vertical(on the side of the calendar view). -To do that, use the `[headerOrientation]` property, setting it respectively to `horizontal` or `vertical` - -### View Orientation Options - -You can set the view orientation to place the months in the calendar either horizontally(side by side) or vertically(above one another). -To do that, use the `[orientation]` property, setting it respectively to `horizontal` or `vertical`. - - -You need at least two month view calendar to see that property working. - +Set `headerOrientation` to place the header `horizontal` (above the view) or `vertical` (beside the view). Set `orientation` to lay the months out `horizontal` (side by side) or `vertical` (stacked). Both default to `horizontal`. ```html @@ -422,234 +276,239 @@ export class CalendarSample9Component { } ``` - + +Set `monthsViewNumber` to at least `2` to see the `orientation` setting take effect. + -## Styling + -### Calendar Theme Property Map +### Handling events -When you modify the `$header-background` and `$content-background` properties, all related theme properties are automatically adjusted to ensure your calendar component is styled consistently. See the tables below for a detailed overview of which theme properties are affected. +Bind to the calendar events to react to selection and navigation: -
+```html +{/* app.component.html */} + + +``` -{/*Theme Switcher Radios and Labels*/} - - - - - - - - +The event emits a single `Date` in `single` selection and a `Date[]` in `multi` or `range` selection, so it is a good place for validation. Alert the user when the selection exceeds 5 days and then reset it: -
+```typescript +// app.component.ts +public onSelection(dates: Date[]) { + if (dates.length > 5) { + this.calendar.selectedDates = []; + // alert the user + } +} +public viewDateChanged(event: IViewDateChangeEventArgs) { + // use event.previousValue to get the previously presented month/year. + // use event.currentValue to get the currently presented month/year. +} - {/* Material Theme Table */} -
+public activeViewChanged(event: CalendarView) { + // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE) +} +``` - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $navigation-hover-color | Hover color for navigation | -| | $navigation-focus-color | Focus color for navigation | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Selected current date background | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for selected current date | -| | $date-selected-current-border-color | Border color for selected current date | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $ym-selected-background | Year/month selected background | -| | $ym-selected-hover-background | Hover background for year/month selected date | -| | $ym-selected-current-background | Current selected year/month background | -| | $ym-selected-current-hover-background | Hover background for current selected year/month | -| | $ym-selected-foreground | Foreground for selected year/month | -| | $ym-selected-hover-foreground | Hover foreground for selected year/month | -| | $ym-selected-current-foreground | Foreground for current selected year/month | -| | $ym-selected-current-hover-foreground | Hover foreground for current selected year/month | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $picker-background | Picker background | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-current-background | Background for the current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-border-color | Border color for the current date | -| | $ym-current-background | Year/month current background | -| | $ym-current-hover-background | Hover background for current year/month | -| | $ym-current-foreground | Foreground for current year/month | -| | $ym-current-hover-foreground | Hover foreground for current year/month | -| | $date-selected-range-background | Selected range background | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-selected-current-range-background | Background for selected current date ranges | -| | $date-selected-current-range-hover-background | Hover background for selected current date ranges | -| | $date-selected-current-range-focus-background | Focus background for selected current date ranges | -| | $date-selected-current-range-foreground | Foreground for selected current date ranges | -| | $date-special-foreground | Foreground for special dates | -| | $date-special-border-color | Border color for special dates | -| | $date-special-hover-border-color | Hover border color for special dates | -| | $date-special-focus-foreground | Focus foreground for special dates | -| | $date-special-range-foreground | Foreground for special date ranges | -| | $date-special-range-border-color | Border color for special date ranges | -| | $date-special-range-hover-background | Hover background for special date ranges | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $date-selected-special-hover-border-color | Hover border color for selected special dates | -| | $date-selected-special-focus-border-color | Focus border color for selected special dates | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Fluent Theme Table */} -
- - | Primary Property | Dependent Property | Description | + + +## Best Practices + +- Match the `selection` mode to the real task — `single` for one date, `multi` for scattered individual picks, `range` for a start/end pair — instead of layering custom logic onto the wrong mode. +- Use `disabledDates` and `specialDates` to communicate availability directly in the grid rather than relying on separate legend text the user has to cross-reference. +- Set `weekStart` and `locale` together when localizing — leaving `weekStart` unset lets the calendar infer it from `locale`, so setting one without the other can produce a week layout that doesn't match the surrounding page's language. +- Don't embed a full Calendar just to capture one date bound to a text field — use the Date Picker instead (see [When Not to Use](#when-not-to-use)). + +## Properties + +{/* Curated core inputs, verified from IgxCalendarComponent. See API References for the complete list. */} + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `selection` | `'single' \| 'multi' \| 'range'` | `'single'` | Selection mode. Changing it resets the current selection. | +| `value` | `Date \| Date[]` | — | Selected date(s): a single `Date` for `single`, otherwise a `Date[]`. | +| `viewDate` | `Date` | current date | The date presented when the calendar renders. | +| `weekStart` | `WEEKDAYS \| number` | locale's first day | Starting day of the week; falls back to the `locale`'s first day. | +| `locale` | `string` | application locale | BCP 47 language tag used for formatting. | +| `formatOptions` | `IFormattingOptions` | `{ day: 'numeric', month: 'long', weekday: 'narrow', year: 'numeric' }` | `Intl` date-format options per view. | +| `formatViews` | `IFormattingViews` | `{ day: false, month: true, year: false }` | Which views apply `formatOptions`. | +| `disabledDates` | `DateRangeDescriptor[]` | `[]` | Ranges that cannot be selected. | +| `specialDates` | `DateRangeDescriptor[]` | `[]` | Highlighted ranges that remain selectable. | +| `showWeekNumbers` | `boolean` | `false` | Displays the week numbers column. | +| `hideOutsideDays` | `boolean` | `false` | Hides days that fall outside the current month. | +| `monthsViewNumber` | `number` | `1` | Number of month views rendered side by side. | +| `hasHeader` | `boolean` | `true` | Renders the calendar header (single selection only). | +| `headerOrientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Header placement relative to the view. | +| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the month views. | +| `activeView` | `IgxCalendarView` | `'month'` | The view in focus (`month`, `year`, or `decade`). | + +## Methods + +| Name | Parameters | Description | | --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $date-current-background | Background for the current date | -| | $date-current-hover-foreground | Hover foreground for the current date | -| | $date-current-focus-foreground | Focus foreground for the current date | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-current-hover-foreground | Hover foreground for the currently selected date | -| | $date-selected-current-focus-foreground | Focus foreground for the currently selected date | -| | $date-special-border-color | Border color for special dates | -| | $date-special-hover-foreground | Hover foreground for special dates | -|**$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $picker-background | Picker background | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-selected-background | Background for selected dates | -| | $date-selected-hover-background | Hover background for selected dates | -| | $date-selected-focus-background | Focus background for selected dates | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-hover-foreground | Hover foreground for selected dates | -| | $date-selected-focus-foreground | Focus foreground for selected dates | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Bootstrap Theme Table */} -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-background | Picker background | -| | $picker-hover-foreground | Picker hover foreground | -| | $weekday-color | Color for weekday labels | -| | $picker-focus-foreground | Picker focus foreground | -| | $date-special-border-color | Border color for special dates | -| | $date-special-focus-foreground | Focus foreground for special dates | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-current-background | Background for the current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-border-color | Border color for the current date | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Background for the currently selected date | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $date-selected-special-hover-border-color | Hover border color for selected special dates | -| | $date-selected-special-focus-border-color | Focus border color for selected special dates | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Indigo Theme Table */} -
- - | Primary Property | Dependent Property | Description | +| `selectDate` | `value: Date \| Date[] \| string` | Selects date(s) according to the current `selection` mode. | +| `deselectDate` | `value?: Date \| Date[] \| string` | Deselects date(s); clears the whole selection when called with no argument. | + +## Events + +| Name | Type | Description | | --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-background | Picker background | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $navigation-hover-color | Navigation hover color | -| | $navigation-focus-color | Navigation focus color | -| | $date-current-background | Background for the current date | -| | $date-current-border-color | Border color for the current date | -| | $date-current-hover-background | Background for hovered current date | -| | $date-current-hover-border-color | Border color for hovered current date | -| | $date-current-focus-background | Background for focused current date | -| | $date-current-focus-border-color | Border color for focused current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-hover-foreground | Foreground for hovered current date | -| | $date-current-focus-foreground | Foreground for focused current date | -| | $date-selected-current-border-color | Border color for the currently selected date | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Background for the currently selected date | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-current-border-color | Border color for the currently selected date | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-selected-current-range-background | Background for the current date in a selected range | -| | $date-selected-current-range-hover-background | Hover background for the current date in a selected range | -| | $date-selected-current-range-foreground | Foreground for the current date in a selected range | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- -
-
{/* .theme-switcher-wrapper */} - -To get started with styling the calendar, we need to import the `index` file, where all the theme functions and component mixins live: +| `selected` | `EventEmitter` | Emitted when date(s) are selected. | +| `viewDateChanged` | `EventEmitter` | Emitted when the presented month or year changes. | +| `activeViewChanged` | `EventEmitter` | Emitted when the active view changes (for example, from month to year). | + +## Styling + +Style the calendar by creating a theme and passing it to the component. The sample below applies a custom `$header-background` and `$content-background`: + + + +All themes expose the same set of variables — only their default values differ per theme. Many of them auto-derive from the primary properties (`$header-background`, `$content-background`) when not set explicitly, so the component stays visually consistent. + +| Variable | Description | +| --- | --- | +| `$size` | Size of days, months, and years views. | +| `$inner-size` | Inner size for calendar elements. | +| `$weekday-color` | Color for weekday labels. Auto-derived from content-background. | +| `$actions-divider-color` | Divider color for date-picker actions. | +| `$border-radius` | Border radius for calendar container. | +| `$content-background` | Background color for calendar. PRIMARY - derives content-foreground, inactive-color, date-hover colors, week-number colors. | +| `$border-color` | Border color for calendar container. | +| `$header-background` | Header background color. PRIMARY - derives header-foreground and most accent/selection colors. | +| `$header-foreground` | Header foreground color. Auto-derived from header-background. | +| `$picker-foreground` | Foreground for the calendar picker. Auto-derived from picker-background. | +| `$picker-background` | Background for the calendar picker. | +| `$picker-hover-foreground` | Hover foreground for the calendar picker. Auto-derived from header-background. | +| `$picker-focus-foreground` | Focus foreground for the calendar picker. Auto-derived from picker-hover-foreground. | +| `$navigation-color` | Icon color for month navigation. Auto-derived from picker-background. | +| `$navigation-hover-color` | Hover color for navigation icons. Auto-derived from picker-hover-foreground. | +| `$navigation-focus-color` | Focus color for navigation icons. Auto-derived from navigation-hover-color. | +| `$ym-border-radius` | Border radius for year/month views. | +| `$ym-hover-foreground` | Hover foreground for year/month. Auto-derived from ym-hover-background. | +| `$ym-hover-background` | Hover background for year/month. Auto-derived from date-hover-background. | +| `$ym-current-outline-color` | Outline color for current year/month. Auto-derived from date-current-border-color. | +| `$ym-current-outline-hover-color` | Hover outline color for current year/month. | +| `$ym-current-outline-focus-color` | Focus outline color for current year/month. | +| `$ym-current-background` | Background for current year/month. | +| `$ym-current-foreground` | Foreground for current year/month. Auto-derived from ym-current-background. | +| `$ym-current-hover-foreground` | Hover foreground for current year/month. | +| `$ym-current-hover-background` | Hover background for current year/month. | +| `$ym-selected-outline-color` | Outline color for selected year/month. | +| `$ym-selected-hover-outline-color` | Hover outline color for selected year/month. | +| `$ym-selected-focus-outline-color` | Focus outline color for selected year/month. | +| `$ym-selected-foreground` | Foreground for selected year/month. Auto-derived from ym-selected-background. | +| `$ym-selected-background` | Background for selected year/month. Auto-derived from header-background. | +| `$ym-selected-hover-foreground` | Hover foreground for selected year/month. | +| `$ym-selected-hover-background` | Hover background for selected year/month. | +| `$ym-selected-current-outline-color` | Outline color for selected current year/month. | +| `$ym-selected-current-outline-hover-color` | Hover outline color for selected current year/month. | +| `$ym-selected-current-outline-focus-color` | Focus outline color for selected current year/month. | +| `$ym-selected-current-foreground` | Foreground for selected current year/month. | +| `$ym-selected-current-background` | Background for selected current year/month. | +| `$ym-selected-current-hover-foreground` | Hover foreground for selected current year/month. | +| `$ym-selected-current-hover-background` | Hover background for selected current year/month. | +| `$week-number-border-radius` | Border radius for week number column. | +| `$week-number-foreground` | Foreground for week number column. Auto-derived from week-number-background. | +| `$week-number-background` | Background for week number column. Auto-derived from content-background. | +| `$content-foreground` | The foreground color for idle dates. Auto-derived from content-background. | +| `$weekend-color` | Color for weekend days. Auto-derived from content-foreground. | +| `$inactive-color` | Color for inactive dates (outside current month). Auto-derived from content-background. | +| `$date-border-radius` | Border radius for date cells. | +| `$date-border-color` | Border color for date cells. | +| `$date-hover-border-color` | Hover border color for date cells. | +| `$date-focus-border-color` | Focus border color for date cells. | +| `$date-hover-background` | Hover background for date cells. Auto-derived from content-background. | +| `$date-focus-background` | Focus background for date cells. Auto-derived from date-hover-background. | +| `$date-hover-foreground` | Hover foreground for date cells. Auto-derived from date-hover-background. | +| `$date-focus-foreground` | Focus foreground for date cells. Auto-derived from date-hover-foreground. | +| `$date-selected-border-color` | Border color for selected date. | +| `$date-selected-hover-border-color` | Hover border color for selected date. | +| `$date-selected-focus-border-color` | Focus border color for selected date. | +| `$date-selected-background` | Background for selected date. Auto-derived from header-background. | +| `$date-selected-foreground` | Foreground for selected date. Auto-derived from date-selected-background. | +| `$date-selected-hover-background` | Hover background for selected date. Auto-derived from date-selected-background. | +| `$date-selected-focus-background` | Focus background for selected date. | +| `$date-selected-hover-foreground` | Hover foreground for selected date. | +| `$date-selected-focus-foreground` | Focus foreground for selected date. | +| `$date-selected-special-border-color` | Border color for selected special date. | +| `$date-selected-special-hover-border-color` | Hover border color for selected special date. | +| `$date-selected-special-focus-border-color` | Focus border color for selected special date. | +| `$date-selected-special-background` | Background for selected special date. | +| `$date-selected-special-foreground` | Foreground for selected special date. | +| `$date-selected-special-hover-background` | Hover background for selected special date. | +| `$date-selected-special-focus-background` | Focus background for selected special date. | +| `$date-selected-special-hover-foreground` | Hover foreground for selected special date. | +| `$date-selected-special-focus-foreground` | Focus foreground for selected special date. | +| `$date-range-border-radius` | Border radius for date range selection. | +| `$date-range-border-color` | Border color for date range selection. | +| `$date-range-preview-border-color` | Preview border color for date range selection. | +| `$date-selected-range-foreground` | Foreground for dates in selected range. | +| `$date-selected-range-background` | Background for dates in selected range. | +| `$date-selected-range-hover-foreground` | Hover foreground for dates in selected range. | +| `$date-selected-range-hover-background` | Hover background for dates in selected range. | +| `$date-selected-range-focus-foreground` | Focus foreground for dates in selected range. | +| `$date-selected-range-focus-background` | Focus background for dates in selected range. | +| `$date-selected-current-range-foreground` | Foreground for current date in selected range. | +| `$date-selected-current-range-background` | Background for current date in selected range. | +| `$date-selected-current-range-hover-foreground` | Hover foreground for current date in selected range. | +| `$date-selected-current-range-hover-background` | Hover background for current date in selected range. | +| `$date-selected-current-range-focus-foreground` | Focus foreground for current date in selected range. | +| `$date-selected-current-range-focus-background` | Focus background for current date in selected range. | +| `$date-current-border-radius` | Border radius for current date. | +| `$date-current-border-color` | Border color for current date. | +| `$date-current-hover-border-color` | Hover border color for current date. | +| `$date-current-focus-border-color` | Focus border color for current date. | +| `$date-current-background` | Background for current date. | +| `$date-current-foreground` | Foreground for current date. | +| `$date-current-hover-background` | Hover background for current date. | +| `$date-current-focus-background` | Focus background for current date. | +| `$date-current-hover-foreground` | Hover foreground for current date. | +| `$date-current-focus-foreground` | Focus foreground for current date. | +| `$date-selected-current-border-color` | Border color for selected current date. | +| `$date-selected-current-hover-border-color` | Hover border color for selected current date. | +| `$date-selected-current-focus-border-color` | Focus border color for selected current date. | +| `$date-selected-current-background` | Background for selected current date. | +| `$date-selected-current-hover-background` | Hover background for selected current date. | +| `$date-selected-current-focus-background` | Focus background for selected current date. | +| `$date-selected-current-foreground` | Foreground for selected current date. | +| `$date-selected-current-hover-foreground` | Hover foreground for selected current date. | +| `$date-selected-current-focus-foreground` | Focus foreground for selected current date. | +| `$date-special-border-radius` | Border radius for special date. | +| `$date-special-border-color` | Border color for special date. | +| `$date-special-hover-border-color` | Hover border color for special date. | +| `$date-special-focus-border-color` | Focus border color for special date. | +| `$date-special-foreground` | Foreground for special date. Auto-derived from header-background. | +| `$date-special-background` | Background for special date. | +| `$date-special-hover-foreground` | Hover foreground for special date. | +| `$date-special-hover-background` | Hover background for special date. | +| `$date-special-focus-foreground` | Focus foreground for special date. | +| `$date-special-focus-background` | Focus background for special date. | +| `$date-special-range-border-color` | Border color for special date in range. | +| `$date-special-range-hover-border-color` | Hover border color for special date in range. | +| `$date-special-range-focus-border-color` | Focus border color for special date in range. | +| `$date-special-range-foreground` | Foreground for special date in range. | +| `$date-special-range-hover-foreground` | Hover foreground for special date in range. | +| `$date-special-range-focus-foreground` | Focus foreground for special date in range. | +| `$date-special-range-background` | Background for special date in range. | +| `$date-special-range-hover-background` | Hover background for special date in range. | +| `$date-special-range-focus-background` | Focus background for special date in range. | +| `$date-disabled-foreground` | Foreground for disabled dates. | +| `$date-disabled-range-foreground` | Foreground for disabled dates in selected range. | + +### Sass Theming + +Import the theming index, where 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 by specifying just the `$header-background` and `$content-background` parameters, the theme will automatically compute appropriate state colors and contrast foregrounds. Of course, you're still free to override any of the theme parameters with custom values if needed. +Create a theme that extends . Specifying just `$header-background` and `$content-background` computes the related state colors and contrast foregrounds automatically, and you can still override any parameter: ```scss $custom-calendar-theme: calendar-theme( @@ -658,7 +517,7 @@ $custom-calendar-theme: calendar-theme( ); ``` -The last step is to pass the custom calendar theme: +Pass the custom theme: ```scss :host { @@ -666,13 +525,11 @@ The last step is to pass the custom calendar theme: } ``` - - -### Styling with Tailwind +### Tailwind -You can style the `calendar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. +Style the calendar with the custom Tailwind utility classes. First, [set up Tailwind](/themes/misc/tailwind-classes). -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: +Along with the Tailwind import in your global stylesheet, add the theme utilities: ```scss @import "tailwindcss"; @@ -680,15 +537,9 @@ Along with the tailwind import in your global stylesheet, you can apply the desi @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-calendar`, `dark-calendar`. - -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.). +The utility file includes both `light` and `dark` variants. Use `light-*` classes for the light theme and `dark-*` classes for the dark theme, appending the component name after the prefix — `light-calendar`, `dark-calendar`. These classes enable dynamic theme calculations, and you 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: +Find the full list of properties in the : ```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. +The exclamation mark (`!`) is required so the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important they get overridden by the component's default theme. -At the end your calendar should look like this: + - +## Accessibility + +### Keyboard Interaction + +When the calendar is focused, use: + +| Key | Action | +| --- | --- | +| PageUp | Move to the previous month | +| PageDown | Move to the next month | +| Shift + PageUp | Move to the previous year | +| Shift + PageDown | Move to the next year | +| Home | Focus the first day of the month, or the first month/year in view | +| End | Focus the last day of the month, or the last month/year in view | +| Arrow keys | Navigate through days, months, or years in the active view (disabled dates are skipped) | +| Enter / Space | Select the focused day, or open/confirm the focused month or year | + +When the previous or next month button in the subheader is focused, press Space or Enter to scroll the next or previous month into view. When the month button is focused, Space or Enter opens the months view; when the year button is focused, it opens the decade view. + +Day navigation is continuous — arrow keys move through days across month boundaries and change the month in view as needed. + + +Tab navigation reaches these stops: the previous-month button, the month button, the year button, the next-month button, and one date in the grid (the selected date, the current date, or the first focusable date). In multi and range selection, only the first selected date is part of the tab sequence; move between dates in the grid with the arrow keys. + + +### Screen Readers / ARIA + +The calendar view exposes `role="grid"` and tracks the focused cell with `aria-activedescendant`, and sets `aria-multiselectable` when `selection` is `multi` or `range`. The navigation buttons and the month/year pickers expose `role="button"` with localized `aria-label`s, and off-screen live regions announce the presented month and year. All labels come from the calendar resource strings, so they follow the component's `locale` and can be overridden through `resourceStrings`. + +### Accessibility Compliance + +Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. + +| Criterion | How the Calendar complies | +| --- | --- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) / [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) | Every view (days, months, years) is fully operable from the keyboard — paging, navigation, and selection all have a documented key binding, and arrow-key navigation moves continuously between days without trapping focus. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The view area exposes `role="grid"` with `aria-activedescendant` for the focused cell and `aria-multiselectable` in `multi`/`range` selection; the navigation and picker buttons expose `role="button"` with localized `aria-label`s. | +| [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html) | Off-screen live regions announce the presented month and year as the user navigates, so the change is available to assistive technology without moving focus. | + +**Your responsibilities** + +- Keep sufficient color contrast between the calendar's background and its date/text colors when customizing the theme — see [Styling](#styling). +- Preserve a logical tab order when embedding the calendar in a custom layout, so the documented Tab stops (navigation buttons, then the grid) stay reachable in sequence. +- If you override `resourceStrings`, keep the replacement labels as descriptive as the defaults they replace. + +## Troubleshooting + +**How do I register the calendar with an `NgModule` instead of the standalone directives?** + +Before standalone components, the calendar was imported through `IgxCalendarModule`. Add it — together with `BrowserAnimationsModule` — to your `AppModule`: + +```typescript +// app.module.ts +import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; +import { IgxCalendarModule } from 'igniteui-angular/calendar'; +// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + imports: [..., BrowserAnimationsModule, IgxCalendarModule], +}) +export class AppModule {} +``` + +Standalone imports (`IGX_CALENDAR_DIRECTIVES` or `IgxCalendarComponent`) are available as of `16.0.0` and are the recommended approach. + +**My Sass `@import` of the theming index no longer resolves.** + +Prior to Ignite UI for Angular version 13, import the themes from the legacy path instead of `@use "igniteui-angular/theming"`: + +```scss +@import '~igniteui-angular/lib/core/styles/themes/index'; +``` + +**Arrow keys don't move focus between days when I press Tab.** + +From version 10.2.0, Tab no longer steps through the days view; use the arrow keys to move between dates. From version 8.2.0, arrow-key navigation does not focus days outside the current month — it changes the month in view instead. ## API References -
+ - - - - -## Additional Resources -
+## Additional Resources Our community is active and always welcoming to new ideas. From c139930fc01f672ea6d765ac833e0e147580a44b Mon Sep 17 00:00:00 2001 From: Hristo Hristov Date: Wed, 15 Jul 2026 10:16:05 +0300 Subject: [PATCH 3/8] feat(docs): update data entry and display section topics --- .../content/en/components/autocomplete.mdx | 93 +++--- .../src/content/en/components/badge.mdx | 240 +++++++++------- .../content/en/components/button-group.mdx | 80 +++++- .../src/content/en/components/button.mdx | 79 ++++- .../src/content/en/components/checkbox.mdx | 85 +++++- .../src/content/en/components/chip.mdx | 89 +++++- .../en/components/circular-progress.mdx | 85 +++++- .../src/content/en/components/divider.mdx | 83 +++++- .../content/en/components/inputs/badge.mdx | 129 ++++++--- .../en/components/inputs/button-group.mdx | 61 +++- .../content/en/components/inputs/button.mdx | 61 +++- .../content/en/components/inputs/checkbox.mdx | 56 +++- .../src/content/en/components/inputs/chip.mdx | 60 +++- .../components/inputs/circular-progress.mdx | 269 ++++-------------- .../en/components/inputs/color-editor.mdx | 88 +++++- .../en/components/inputs/linear-progress.mdx | 79 ++--- .../content/en/components/layouts/divider.mdx | 62 +++- 17 files changed, 1181 insertions(+), 518 deletions(-) diff --git a/docs/angular/src/content/en/components/autocomplete.mdx b/docs/angular/src/content/en/components/autocomplete.mdx index 0a4812c6a6..01573311d4 100644 --- a/docs/angular/src/content/en/components/autocomplete.mdx +++ b/docs/angular/src/content/en/components/autocomplete.mdx @@ -11,24 +11,43 @@ 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 Autocomplete Directive Overview +# Autocomplete Directive Angular Autocomplete is a search box directive that enables users to easily find, filter and select an item from a list of suggestions while they type. Feature-rich, it supports seamless data binding, filtering, grouping, UI customization options, and other built-in functionalities so developers can create intuitive autocomplete search experience. -
+## Overview The directive provides a way to enhance a text input by showing an with suggested options, provided by the developer. The suggestions will show once you start typing in the text input or use the `Arrow Up`/`Arrow Down` keys. -
-## Angular Autocomplete Example +### When to Use + +Use the autocomplete directive when a text input should suggest matching options as the user types — searching a long list of towns, users, or products. + +### When Not to Use + +When users must pick from a small, fixed list without typing, use the directly instead of layering autocomplete on an input. + +## Live Demo The Angular Autocomplete example below generates a dropdown suggestion list as users start typing the name of a town in the input textbox. -
+## Anatomy + +{/* TODO: add an annotated screenshot of the input, suggestion list, list items, and active item. */} -## Getting Started with Ignite UI for Angular Autocomplete +The autocomplete combines an input enhanced with `igxAutocomplete` and an `igxDropDown` that provides the suggestions. + +```text +Input element +└── igxAutocomplete directive + └── igxDropDown + ├── igxDropDownItemGroup (optional) + └── igxDropDownItem +``` + +## Getting Started To get started with the Ignite UI for Angular for [Angular Components](https://www.infragistics.com/products/ignite-ui-angular) and Autocomplete directive in particular, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: @@ -94,7 +113,7 @@ export class HomeComponent {} Now that you have the Ignite UI for Angular Action Strip module or directive imported, you can start with a basic configuration of the `igxAutocomplete` component. -## Using the Angular Autocomplete +## Usage In order to apply the autocomplete functionality to an input, add the `igxAutocomplete` directive, referencing the dropdown: @@ -225,9 +244,26 @@ If everything went right, you should see this in your browser:
-## Keyboard Navigation +## Best Practices -
+- Keep the suggestion list short enough to scan quickly and provide filtering for long lists. +- Use clear labels and preserve the input value when the user selects a suggestion. +- Do not use autocomplete when the available choices are few and fixed; use a dropdown instead. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | See API reference | See API reference | Disables autocomplete interaction when set. | +| | See API reference | See API reference | Configures dropdown positioning, scrolling, and outlet behavior. | + +## Styling + +Every component has its own theme. To get the `igxAutocomplete` styled, style its containing components — the and the . See the [`igxInputGroup`](/input-group#styling) and [`igxDropdown`](/drop-down#styling) styling sections. + +## Accessibility + +### Keyboard Interaction - ⬆ / ⬇ or typing in the input will open the dropdown, if it's closed. - ⬇ - will move to the next dropdown item. @@ -239,51 +275,42 @@ If everything went right, you should see this in your browser: When the Angular autocomplete opens, then the first item on the list is automatically selected. The same is valid when the list is filtered. -You can also see how our [WYSIWYG App Builder™](https://www.infragistics.com/products/appbuilder) streamlines the entire design-to-code story by 80% using real Angular components. - -## Compatibility support +### Screen Readers / ARIA Applying the `igxAutocomplete` directive will decorate the element with the following ARIA attributes: -- role="combobox" - role of the element, where the directive is applied. -- aria-autocomplete="list" - indicates that input completion suggestions are provided in the form of list -- aria-haspopup="listbox" attribute to indicate that `igxAutocomplete` can pop-up a container to suggest values. -- aria-expanded="true"/"false" - value depending on the collapsed state of the dropdown. -- aria-owns="dropDownID" - id of the dropdown used for displaying suggestions. -- aria-activedescendant="listItemId" - value is set to the id of the current active list element. +- role="combobox" +- aria-autocomplete="list" +- aria-haspopup="listbox" +- aria-expanded="true"/"false" +- aria-owns="dropDownID" +- aria-activedescendant="listItemId" -The `drop-down` component, used as provider for suggestions, will expose the following ARIA attributes: +The `drop-down` component exposes `listbox`, `group`, and `option` roles for its suggestion containers and items. -- role="listbox" - applied on the `igx-drop-down` component container -- role="group" - applied on the `igx-drop-down-item-group` component container -- role="option" - applied on the `igx-drop-down-item` component container -- aria-disabled="true"/"false" applied on `igx-drop-down-item`, `igx-drop-down-item-group` component containers when they are disabled. +## Troubleshooting -## Styling - -Every component has its own theme. +### Why does the suggestion list not open? -To get the `igxAutocomplete` styled, you have to style its containing components. In our case, these are the and the . +Make sure the input references an `igxDropDown` through the `igxAutocomplete` directive and that the dropdown contains items to display. -Take a look at the [`igxInputGroup`](/input-group#styling) and the [`igxDropdown`](/drop-down#styling) styling sections to get a better understanding of how to style those two components. +### Why are suggestions not filtered? -## API Reference +The directive displays the provided items but does not define the filtering rule. Filter the collection before rendering the dropdown items. -
+## API References - - - -## Theming Dependencies +## Dependencies - - ## Additional Resources -
- - [IgxDropDown](/drop-down) - [IgxInputGroup](/input-group) - [Template Driven Forms Integration](/input-group) diff --git a/docs/angular/src/content/en/components/badge.mdx b/docs/angular/src/content/en/components/badge.mdx index 037ff5c5ba..0d2c6f46cc 100644 --- a/docs/angular/src/content/en/components/badge.mdx +++ b/docs/angular/src/content/en/components/badge.mdx @@ -1,61 +1,67 @@ --- title: Angular Badge Component – Ignite UI for Angular | Infragistics | MIT license -description: Display an active count or icon in a predefined style to decorate other components anywhere in an application with Ignite UI for Angular Badge control. +description: Use the Ignite UI for Angular Badge component to display status indicators — counts, icons, or dot notifications — on top of avatars, icons, and navigation items. keywords: Angular Badge component, Angular Badge control, Ignite UI for Angular, Angular UI Components license: MIT llms: - description: "Angular Badge is a component used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed." + description: "Use the Angular Badge component to display notification counts, status labels, or dot indicators on avatars, icons, and navigation items." --- 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 Badge Component Overview +# Badge Component -
-Angular Badge is a component used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed. Badges are usually designed as icons with a predefined style to communicate information, success, warnings, or errors. -
+Angular Badge is a component used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed. Badges are usually designed as icons with a predefined style to communicate information, success, warnings, or errors. -## Angular Badge Example +## Overview - +### When to Use -
+- Add a count or status indicator to an icon, avatar, or navigation item (e.g. unread messages, cart quantity). +- Show a contextual label — `success`, `warning`, `error`, or `default` — on a list item or card. +- Signal new activity with a minimal dot when the exact count is not relevant. -## Getting Started with Ignite UI for Angular Badge +### When Not to Use -To get started with the Ignite UI for Angular Badge component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: +- When the indicator must be interactive (clickable or dismissible) — use an instead. +- When you need a standalone label with its own layout — use a chip or tag component. -```cmd -ng add igniteui-angular -``` +## Live Demo -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 `IgxBadgeModule` in your **app.module.ts** file. +## Anatomy -```typescript -// app.module.ts +{/* TODO: add an annotated screenshot or GIF of the badge showing its icon, value, and host element. */} -... -import { IgxBadgeModule } from 'igniteui-angular/badge'; -// import { IgxBadgeModule } from '@infragistics/igniteui-angular'; for licensed package +The badge is a single host element that can show an icon, a value, or projected content. Place it inside a relatively positioned host when it decorates another component, such as an avatar or icon. -@NgModule({ - ... - imports: [..., IgxBadgeModule], - ... -}) -export class AppModule {} ``` +Relative-positioned host element +├── Decorated element // e.g. igx-avatar or an icon button +└── igx-badge // badge host; position it over the decorated element + ├── icon (optional) // set with the `icon` input + ├── value (optional) // set with the `value` input + └── projected content (optional) // custom icon, text, or other template content +``` + +## Getting Started + +To get started with the Ignite UI for Angular Badge component, first install Ignite UI for Angular. In an existing Angular application, run: + +```cmd +ng add igniteui-angular +``` + +For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. -Alternatively, as of `16.0.0` you can import the `IgxBadgeComponent` as a standalone dependency. +Import `IgxBadgeComponent` as a standalone dependency: ```typescript // home.component.ts -... import { IgxBadgeComponent } from 'igniteui-angular/badge'; // import { IgxBadgeComponent } from '@infragistics/igniteui-angular'; for licensed package @@ -63,7 +69,6 @@ import { IgxBadgeComponent } from 'igniteui-angular/badge'; selector: 'app-home', template: '', styleUrls: ['home.component.scss'], - standalone: true, imports: [IgxBadgeComponent] }) export class HomeComponent {} @@ -73,31 +78,17 @@ 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 Badge module or component imported, you can start with a basic configuration of the `igx-badge` component. - -## Using the Angular Badge Component +## Usage -Let's see how the demo sample is done. It's a simple success badge on an avatar. To build that, we need to import the `IgxAvatarModule`, along with the `IgxBadgeModule`: +The following example shows a success badge overlaid on an avatar. Import `IgxAvatarComponent` alongside `IgxBadgeComponent`: ```typescript -// app.module.ts -... -import { IgxBadgeModule } from 'igniteui-angular/badge'; -import { IgxAvatarModule } from 'igniteui-angular/avatar'; -// import { IgxBadgeModule, IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxBadgeModule, IgxAvatarModule], - ... -}) - -export class AppModule {} +import { IgxBadgeComponent } from 'igniteui-angular/badge'; +import { IgxAvatarComponent } from 'igniteui-angular/avatar'; +// import { IgxBadgeComponent, IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package ``` -_Alternatively, as of `16.0.0` you can import the `IgxBadgeComponent` and `IgxAvatarComponent` as standalone dependencies._ - -Next, we will add those components to our template: +Add the components to the template: ```html
@@ -107,7 +98,7 @@ Next, we will add those components to our template:
``` -Using the wrapper, we will position the badge absolutely, covering a little bit of the avatar: +Position the badge absolutely over the avatar: ```scss .wrapper { @@ -122,17 +113,15 @@ igx-badge { } ``` -### Badge Shape +### Shape -We can change the badge shape through the `shape` attribute setting its value to `square`. By default, the shape of the badge is `rounded`. +Change the badge shape through the `shape` attribute. By default, the shape is `rounded`; set it to `square` for a square badge: ```html ``` -If everything's done right, you should see the demo sample shown above in your browser. - -### Badge Size +### Size The size of the badge can be controlled using the `--size` variable. It will make sure that the badge sizes proportionally in both directions. Keep in mind, however, that badges containing text values use the `caption` typography style for its font-size and line-height. For that reason, when setting the `--size` of a badge containing text to values below 16px, you will also need to modify its typography. @@ -147,7 +136,7 @@ igx-badge { } ``` -### Badge Value and Icon +### Value and Icon Use the `[value]` input to display text or a numeric count inside the badge: @@ -180,9 +169,9 @@ Or you can project content directly: ``` -### Badge Icon +### Icon -In addition to material icons, the `igx-badge` component also supports usage of [Material Icons Extended](/material-icons-extended) and any other custom icon set. To add an icon from the material icons extended set inside your badge component, first you have to register it: +In addition to material icons, the `igx-badge` component also supports usage of [Material Icons Extended](/material-icons-extended) and any other custom icon set. To add an icon from the Material Icons Extended set, register it first: ```ts export class BadgeIconComponent implements OnInit { @@ -200,43 +189,19 @@ Then, just specify the icon name and family as follows: ``` - + -### Dot Badge +### Dot The `igx-badge` component can also render as a minimal dot indicator for notifications by enabling its `dot` property. Dot badges do not support content, but they can be outlined and can use any of the available dot types (e.g., primary, success, info, etc.). - - -### Badge in List - -Let's extend the previous sample and create a list with contacts, similar to those in chat clients. In addition to the contact name, we want to display an avatar and the current state of the contact (online, offline or away). To achieve this, we're using the and components. For a container, is used. - -To continue, include all needed modules and import them in the **app.module.ts** file. - -```typescript -// app.module.ts - -... -import { IgxListModule } from 'igniteui-angular/list'; -import { IgxAvatarModule } from 'igniteui-angular/avatar'; -import { IgxBadgeModule } from 'igniteui-angular/badge'; -// import { IgxListModule, IgxAvatarModule, IgxBadgeModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxListModule, IgxAvatarModule, IgxBadgeModule], -}) -export class AppModule {} -``` + - -The has and inputs to configure the badge look. You can set the icon by providing its name from the official [material icons set](https://material.io/icons/). The badge type can be set to either `Default`, `Info`, `Success`, `Warning`, or `Error`. Depending on the type, a specific background color is applied. - +### In a List -In our sample, and are bound to model properties named _icon_ and _type_. +The following example shows a contacts list where each item uses a badge to display the contact's online/away/offline status. It combines , , and . -Next, we're adding the contacts in our template: +Import the standalone components: ```html {/* contacts.component.html */} @@ -264,7 +229,7 @@ Next, we're adding the contacts in our template: ``` -We're going to create our members in the typescript file like this: +Define the members model: ```typescript // contacts.component.ts @@ -309,7 +274,7 @@ class Member { } ``` -Position the badge in its parent container: +Position the badge in the parent container: ```css /* contacts.component.css */ @@ -337,7 +302,35 @@ Position the badge in its parent container: If the sample is configured properly, a list of members should be displayed and every member has an avatar and a badge, showing its current state. - + + +## Best Practices + +Follow these guidelines to use the Badge component effectively. + +**Do:** +- Position the badge on the top-right corner of its host element using absolute/relative positioning. +- Use the `dot` variant when only presence of a notification matters and count is irrelevant. +- Use semantic types (`success`, `warning`, `error`, `info`) to communicate status at a glance. +- Pair the badge with an accessible label on its host element so screen readers announce the count or status. + +**Don't:** +- Don't use a badge as the only means of conveying critical information — always provide a text alternative. +- Don't stack multiple badges on a single element; simplify to one indicator. +- Don't use a badge for interactive actions — use a Chip or Button instead. + +## Properties + +Use these core inputs to configure the component. See the generated API reference for the complete type and default-value details. + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | See API reference | See API reference | Displays a Material or registered custom icon in the badge. | +| | See API reference | See API reference | Sets the icon family used to resolve a custom icon. | +| | See API reference | See API reference | Displays text or a numeric count in the badge. | +| | See API reference | See API reference | Applies a semantic badge style, such as success, warning, or error. | +| | See API reference | See API reference | Controls whether the badge uses the rounded or square shape. | +| | See API reference | See API reference | Renders the badge as a minimal notification dot without content. | ## Styling @@ -350,7 +343,7 @@ Changing the `$background-color` property automatically updates the following de | **$background-color** | $icon-color | The color used for icons in the badge. | | | $text-color | The color used for text in the badge. | -To get started with styling the badges, we need to import the `index` file, where all the theme functions and component mixins live: +To get started with styling the badge, import the `index` file, where all the theme functions and component mixins live: ```scss @use "igniteui-angular/theming" as *; @@ -359,7 +352,7 @@ To get started with styling the badges, we need to import the `index` file, wher // @import '~igniteui-angular/lib/core/styles/themes/index'; ``` -Following the simplest approach, we create a new theme that extends the and accepts some parameters that style the badge's items. When you set the `$background-color`, the `$icon-color` and `$text-color` are automatically assigned based on which offers better contrast—black or white. Note that the `$border-radius` property only takes effect when the badge's `shape` is set to `square`. +Create a new theme extending the and accepts some parameters that style the badge's items. When you set the `$background-color`, the `$icon-color` and `$text-color` are automatically assigned based on which offers better contrast—black or white. Note that the `$border-radius` property only takes effect when the badge's `shape` is set to `square`. ```scss $custom-badge-theme: badge-theme( @@ -416,8 +409,63 @@ At the end your badges should look like this: +## Accessibility + +The Angular Badge exposes status information to assistive technologies. Keep the badge text concise and ensure the surrounding interface still communicates the meaning of a status or count. + +### Keyboard Interaction + +The Badge is non-interactive and does not provide keyboard commands or receive focus. Keyboard interaction belongs to the element it decorates, such as a button, link, or list item. + +| Key | Action | +| --- | --- | +| Tab | The Badge is not included in the tab order. Focus moves to the interactive host element, when one exists. | + +### Screen Readers / ARIA + +The component renders with the `status` role by default. Its default `aria-label` is `badge`, and it provides an `aria-roledescription` that identifies the badge type and its icon or value. The component updates this description when its `type`, `icon`, or `value` changes. + +Set a meaningful accessible label when the default label does not describe the notification in its surrounding context. For example, a badge showing an unread-message count should have a label that identifies the count and what it represents. + +| Attribute | Component behavior | +| --- | --- | +| `role` | Defaults to `status`. | +| `aria-label` | Defaults to `badge`; set the component `label` property to provide a contextual label. | +| `aria-roledescription` | Describes the badge type and its icon or value. | + +### Accessibility Compliance + +The component source verifies its exposed role, label, and role description, but those implementation details are not a product-level accessibility-conformance claim. No Badge-specific WCAG or VPAT evidence is cited on this page. + +When using a Badge, ensure the surrounding UI communicates the same status without relying only on color, retains a logical focus order, and preserves sufficient contrast when you customize its theme. + +## Troubleshooting + +### Why is my badge empty? + +**Cause:** The Badge has neither an `icon` nor a `value`. When both inputs are unset, the component does not render badge content. + +**Fix:** Set the `icon` or `value` input, or project custom content into the `igx-badge` element. + +```html + +``` + +### How do I use the Badge in an NgModule-based application? + +**Cause:** The current setup uses standalone component imports. Applications that still use NgModules must import `IgxBadgeModule` instead. + +**Fix:** Import `IgxBadgeModule` in the NgModule that declares the template using `igx-badge`. + +```typescript +import { IgxBadgeModule } from 'igniteui-angular/badge'; +// import { IgxBadgeModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ imports: [IgxBadgeModule] }) +export class AppModule {} +``` + ## API References -
- - - @@ -430,8 +478,6 @@ At the end your badges should look like this: ## 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) diff --git a/docs/angular/src/content/en/components/button-group.mdx b/docs/angular/src/content/en/components/button-group.mdx index 10e8c3eea4..26f5e35e8b 100644 --- a/docs/angular/src/content/en/components/button-group.mdx +++ b/docs/angular/src/content/en/components/button-group.mdx @@ -11,19 +11,38 @@ 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 +# Button Group Component -
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 +## Overview + +### When to Use + +Use the button group to present a set of related, mutually exclusive or multi-select toggle options — text alignment, view mode, or filter toggles. + +### When Not to Use + +For a single, standalone actionable button, use the directive instead. + +## Live Demo -
+## Anatomy + +{/* TODO: add an annotated screenshot of the button group container and its button items. */} + +The button group contains a group host and one or more button items. Selection and alignment are applied to the group and its items. -## Getting Started with Ignite UI for Angular Button Group +```text +Button group +├── button item +├── button item +└── button item +``` + +## Getting Started 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: @@ -93,7 +112,7 @@ 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 +## Usage ### Add Button Group @@ -117,8 +136,6 @@ Use the selector to wrap ``` -## Examples - ### Alignment Use the input property to set the orientation of the buttons in the button group. @@ -246,6 +263,26 @@ public ngOnInit() { +## Best Practices + +- Group only related actions and use a clear label or surrounding context to describe the choices. +- Use single selection for mutually exclusive views and multi-selection only when combinations are meaningful. +- Keep the selected state visible and do not use a button group for unrelated actions. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | See API reference | See API reference | Sets the horizontal or vertical alignment of the button items. | +| | See API reference | See API reference | Controls whether selection is disabled, single, or multiple. | +| | See API reference | See API reference | Supplies the button item definitions displayed by the group. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| `selected` | See API reference | Emitted when the selected button item changes. | + ## Styling ### Button Group Theme Property Map @@ -347,13 +384,32 @@ At the end your button group should look like this: +## Accessibility + +### Keyboard Interaction + +Use `Tab` to reach the group and the arrow keys to move between grouped buttons when the group manages roving focus. + +### Screen Readers / ARIA + +Provide a label in the surrounding context and ensure that each button has a meaningful accessible name. + +### Accessibility Compliance + +The conformance target must be verified against the product accessibility statement before making a compliance claim. + +## Troubleshooting + +### Why is selection not changing? + +Check the configured selection mode and make sure the items are not disabled. For custom values, verify that each item has the expected selection configuration. + ## API References -
- - - - -## Theming Dependencies +## Dependencies - - @@ -361,8 +417,6 @@ At the end your button group should look like this: ## 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) diff --git a/docs/angular/src/content/en/components/button.mdx b/docs/angular/src/content/en/components/button.mdx index 3e27a70f33..0ea54bd30f 100644 --- a/docs/angular/src/content/en/components/button.mdx +++ b/docs/angular/src/content/en/components/button.mdx @@ -11,23 +11,41 @@ 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 Overview +# Button Directive Angular Button directive is used for creating and adding actionable buttons to a web page/application. There are different Angular Button types that are easy to customize and include several built-in features. By default, Angular Material uses native `
- + ### Data Virtualization and Performance @@ -125,7 +124,7 @@ Full support for exporting data grids to XLSX, XLS, TSV or CSV. The Ignite UI fo
Icon representation of Microsoft Excel-like features on the Angular Data Grid
-## Angular Grid Features +### Grid Feature Index - [Inline Editing](/grid/editing) @@ -156,6 +155,15 @@ Full support for exporting data grids to XLSX, XLS, TSV or CSV. The Ignite UI fo - [ARIA/a11y Support](/interactivity/accessibility-compliance) +## Next Steps +Start with the [Angular Data Grid getting started guide](/grid/grid), then choose focused guides for [paging](/grid/paging), [filtering](/grid/filtering), [editing](/grid/editing), [selection](/grid/selection), or [virtualization](/grid/virtualization). + +## API References +Use the [Angular Data Grid API reference](/grid/api) for the complete list of supported inputs, outputs, methods, and configuration options. + +## Additional Resources +Review the [Angular List documentation](/list), [Angular Tree Grid documentation](/tree-grid), and [accessibility guidance](/interactivity/accessibility-compliance) when selecting and configuring a data presentation component. +
-

Ignite UI for Angular Supported Browsers

+

Ignite UI for Angular Supported Browsers

The Angular Data Grid is supported on all modern web browsers, including: @@ -181,7 +189,7 @@ Full support for exporting data grids to XLSX, XLS, TSV or CSV. The Ignite UI fo
-

Ignite UI for Angular Support Options

+

Ignite UI for Angular Support Options

There are multiple options to get access to our award-winning support at Infragistics for the Angular product. @@ -197,11 +205,11 @@ Full support for exporting data grids to XLSX, XLS, TSV or CSV. The Ignite UI fo
-## Ignite UI for Angular Trial License and Commercial +### Ignite UI for Angular Trial License and Commercial Ignite UI for Angular is a commercially licensed product available via a subscription model. You can try the Ignite UI for Angular product for free when you register for a 30-day trial. When you are done with your Trial Period, you can purchase a license from our web site or by calling sales in your region. -## Frequently Asked Questions +### Frequently Asked Questions From f40ded94adf33b1bc76f5e66ec1d4149debb53d4 Mon Sep 17 00:00:00 2001 From: Hristo Hristov Date: Fri, 17 Jul 2026 10:52:31 +0300 Subject: [PATCH 7/8] feat(docs): remove platform name from the xplat topic titles --- docs/xplat/src/content/en/components/inputs/badge.mdx | 2 +- docs/xplat/src/content/en/components/inputs/button-group.mdx | 2 +- docs/xplat/src/content/en/components/inputs/button.mdx | 2 +- docs/xplat/src/content/en/components/inputs/checkbox.mdx | 2 +- docs/xplat/src/content/en/components/inputs/chip.mdx | 2 +- .../src/content/en/components/inputs/circular-progress.mdx | 2 +- docs/xplat/src/content/en/components/inputs/color-editor.mdx | 2 +- docs/xplat/src/content/en/components/inputs/dropdown.mdx | 2 +- docs/xplat/src/content/en/components/inputs/linear-progress.mdx | 2 +- docs/xplat/src/content/en/components/layouts/divider.mdx | 2 +- 10 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/xplat/src/content/en/components/inputs/badge.mdx b/docs/xplat/src/content/en/components/inputs/badge.mdx index af3c80c44c..83f9d2eb68 100644 --- a/docs/xplat/src/content/en/components/inputs/badge.mdx +++ b/docs/xplat/src/content/en/components/inputs/badge.mdx @@ -12,7 +12,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Badge Component +# Badge Component The {Platform} Badge is a component used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed. Badges are usually designed with predefined styles to communicate information, success, warnings, or errors. 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 1052f7564f..285a7fd006 100644 --- a/docs/xplat/src/content/en/components/inputs/button-group.mdx +++ b/docs/xplat/src/content/en/components/inputs/button-group.mdx @@ -13,7 +13,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Button Group Component +# 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. diff --git a/docs/xplat/src/content/en/components/inputs/button.mdx b/docs/xplat/src/content/en/components/inputs/button.mdx index cd60ad7d00..5239fb71b7 100644 --- a/docs/xplat/src/content/en/components/inputs/button.mdx +++ b/docs/xplat/src/content/en/components/inputs/button.mdx @@ -12,7 +12,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Button Component +# Button Component diff --git a/docs/xplat/src/content/en/components/inputs/checkbox.mdx b/docs/xplat/src/content/en/components/inputs/checkbox.mdx index f97ca2c157..c4c5605934 100644 --- a/docs/xplat/src/content/en/components/inputs/checkbox.mdx +++ b/docs/xplat/src/content/en/components/inputs/checkbox.mdx @@ -13,7 +13,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Checkbox Component +# Checkbox Component The {Platform} Checkbox is a component that lets you add checkboxes to your {Platform} apps. It behaves as a standard HTML checkbox, enabling users to select basic checked and unchecked states or an additional indeterminate state. You also get full control over the styling of the {Platform} checkbox component and ability to use it with forms. diff --git a/docs/xplat/src/content/en/components/inputs/chip.mdx b/docs/xplat/src/content/en/components/inputs/chip.mdx index bb3a455cbc..692b921bad 100644 --- a/docs/xplat/src/content/en/components/inputs/chip.mdx +++ b/docs/xplat/src/content/en/components/inputs/chip.mdx @@ -12,7 +12,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Chip Component +# Chip Component {ProductName} Chips help people enter information, make selections, filter content, or trigger actions. diff --git a/docs/xplat/src/content/en/components/inputs/circular-progress.mdx b/docs/xplat/src/content/en/components/inputs/circular-progress.mdx index 0a6f4a34af..3fa17aa581 100644 --- a/docs/xplat/src/content/en/components/inputs/circular-progress.mdx +++ b/docs/xplat/src/content/en/components/inputs/circular-progress.mdx @@ -11,7 +11,7 @@ import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBloc import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Circular Progress Component +# Circular Progress Component The {ProductName} Circular Progress Indicator provides a compact visual representation of determinate or indeterminate progress. diff --git a/docs/xplat/src/content/en/components/inputs/color-editor.mdx b/docs/xplat/src/content/en/components/inputs/color-editor.mdx index d1560e6179..f38fd5d526 100644 --- a/docs/xplat/src/content/en/components/inputs/color-editor.mdx +++ b/docs/xplat/src/content/en/components/inputs/color-editor.mdx @@ -14,7 +14,7 @@ import Badge from 'igniteui-astro-components/components/mdx/Badge.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Color Editor Component +# Color Editor Component The {ProductName} Color Editor is a lightweight color picker component. The Color Editor can pop open by clicking the brush icon. Both the rgba and hex values can be obtained from the desired color along the bottom. These values will update when the three sliders are modified. The center box is designed for adjusting the saturation and brightness along with two adjacent sliders for adjusting the rgb and luminance values. Rgb registers between (1-255). The lightness registers between(0-1). ## Overview diff --git a/docs/xplat/src/content/en/components/inputs/dropdown.mdx b/docs/xplat/src/content/en/components/inputs/dropdown.mdx index 587afe32d4..3e8b3dee13 100644 --- a/docs/xplat/src/content/en/components/inputs/dropdown.mdx +++ b/docs/xplat/src/content/en/components/inputs/dropdown.mdx @@ -13,7 +13,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Dropdown List Component +# Dropdown List Component Feature-rich, the {Platform} Dropdown list offers out-of-the-box filtering, accessibility, preselected values, flexible data binding, grouping, UI customization, and more. What this component practically does is to effectively and easily replace HTML select tags, enabling users to quickly choose a non-editable value from a predefined set of several options. diff --git a/docs/xplat/src/content/en/components/inputs/linear-progress.mdx b/docs/xplat/src/content/en/components/inputs/linear-progress.mdx index 3dc4222229..4aa65e2c82 100644 --- a/docs/xplat/src/content/en/components/inputs/linear-progress.mdx +++ b/docs/xplat/src/content/en/components/inputs/linear-progress.mdx @@ -12,7 +12,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Linear Progress Component +# Linear Progress Component The {ProductName} Linear Progress Indicator component provides a visual indicator of an application’s process as it changes. The indicator updates its appearance as its state changes. Also, you can style this component with a choice of colors in stripes or solids. diff --git a/docs/xplat/src/content/en/components/layouts/divider.mdx b/docs/xplat/src/content/en/components/layouts/divider.mdx index d673acc0ba..c7cd7ac563 100644 --- a/docs/xplat/src/content/en/components/layouts/divider.mdx +++ b/docs/xplat/src/content/en/components/layouts/divider.mdx @@ -12,7 +12,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Divider Component +# Divider Component The {ProductName} Divider allows the content author to easily create a horizontal/vertical rule as a break between content to better organize information on a page. From fe7c33b00ac94f52cfd80b90fac0b7acad62ef30 Mon Sep 17 00:00:00 2001 From: Hristo Hristov Date: Fri, 17 Jul 2026 12:01:13 +0300 Subject: [PATCH 8/8] feat(docs): update the grids and lists topics --- .../content/en/components/grids-and-lists.mdx | 2 +- .../en/components/grids/grids-header.mdx | 49 ++++++++++++------- 2 files changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/angular/src/content/en/components/grids-and-lists.mdx b/docs/angular/src/content/en/components/grids-and-lists.mdx index 91172ea603..b2d00f04fb 100644 --- a/docs/angular/src/content/en/components/grids-and-lists.mdx +++ b/docs/angular/src/content/en/components/grids-and-lists.mdx @@ -18,7 +18,7 @@ import FeatureList from 'docs-template/components/mdx/FeatureList.astro'; [//]: # () -# Angular Grids and Lists +# Grids and Lists Ignite UI for Angular provides components for displaying, navigating, editing, and analyzing structured data in Angular applications. ## Types diff --git a/docs/xplat/src/content/en/components/grids/grids-header.mdx b/docs/xplat/src/content/en/components/grids/grids-header.mdx index 9c38d7aa1b..1835ee4aea 100644 --- a/docs/xplat/src/content/en/components/grids/grids-header.mdx +++ b/docs/xplat/src/content/en/components/grids/grids-header.mdx @@ -1,40 +1,42 @@ --- -title: "{Platform} Grids & Tables | Fastest {Platform} UI Grid | Infragistics" -description: Looking for fast {Platform} grids and tables? {ProductName} provides a complete library of {Platform}-native, Material-based UI data grids and tables. Find more. +title: "{Platform} Grids and Lists | {ProductName}" +description: "{ProductName} provides {Platform} components for displaying, navigating, editing, and analyzing structured data in grids, lists, and tree grids." keywords: "{Platform} data grid, table, grids, {ProductName}, Infragistics" license: commercial mentionedTypes: ["Infragistics.Controls.Grid"] llms: - description: "{ProductName} provides a complete library of {Platform}-native, Material-based UI components, including the world’s fastest virtualized {Platform} data grid." + description: "{ProductName} provides {Platform} components for displaying, navigating, editing, and analyzing structured data in grids, lists, and tree grids." --- 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 Feature from 'docs-template/components/mdx/Feature.astro'; import CtaArea from 'docs-template/components/mdx/CtaArea.astro'; import FeatureList from 'docs-template/components/mdx/FeatureList.astro'; import FaqAccordion from 'docs-template/components/mdx/FaqAccordion.astro'; import BrowserList from 'docs-template/components/mdx/BrowserList.astro'; -# The Fastest {Platform} Grid +# Grids and Lists -{ProductName} provides a complete library of {Platform}-native, Material-based UI components, including the world’s fastest virtualized {Platform} data grid. +{ProductName} provides components for displaying, navigating, editing, and analyzing structured data in {Platform} applications. -## {Platform} Grid Example +## Types +Use a data grid for tabular data, a list for a one-dimensional collection, and a tree grid for hierarchical rows. -In this {Platform} grid example, you can see how users can customize their _data view_ by leveraging the various features built into the grid, like data search and filtering, columns sorting, resizing, pinning and hiding, row selection, export to excel and csv, horizontal and vertical scrolling. We have provided examples for cell templating that includes components like linear progress bar indicator and sparkline. View more features in this [topic](#{PlatformLower}-grid-features). - - +### {Platform} Data Grid +Display tabular data with column-based operations such as sorting, filtering, editing, grouping, summaries, selection, and export. See the [{Platform} Data Grid documentation](data-grid.md). -## What is a {Platform} Grid? - -The {Platform} data grid is a component used to display tabular data in a series of rows and columns. Data grids, also known as tables, are well known in the desktop world with popular software such as Microsoft Excel. While grids have been available on desktop platforms for a long time, they have recently become part of web app UIs, such as {Platform} UI. Modern grids can be complex and may include a range of functionalities, including data binding, editing, Excel-like filtering, custom sorting, grouping, row reordering, row and column freezing, row aggregation, and exporting to Excel, CSV, and pdf formats. + +In this {Platform} grid example, you can see how users can customize their _data view_ by leveraging the various features built into the grid, like data search and filtering, columns sorting, resizing, pinning and hiding, row selection, export to excel and csv, horizontal and vertical scrolling. We have provided examples for cell templating that includes components like linear progress bar indicator and sparkline. View more features in this [topic](#{PlatformLower}-grid-features). -## Why Use a {Platform} Grid? +### {Platform} List +Present a one-dimensional collection of items when users need to browse or select records without a column layout. See the [{Platform} List documentation](list.md). -{Platform} data grids are essential in use cases where lots of data must be stored and sorted through quickly. This can include industries such as financial or insurance that use high-volume, high-velocity data frequently. Often the success of these companies is dependent on the functionality and performance of these data grids. When stock decisions need to be made in microseconds, for example, it’s imperative that the data grid performs with no lag time or flicker. +### {Platform} Tree Grid +Present hierarchical data in rows and columns when users need to expand, collapse, and work with parent-child relationships. See the [{Platform} Tree Grid documentation](tree-grid.md). ## Key Features @@ -182,7 +184,7 @@ Seamlessly scroll through unlimited rows and columns in your {Platform} grid, wi -## {Platform} Grid Features +### {Platform} Grid Features
  • @@ -297,11 +299,20 @@ Seamlessly scroll through unlimited rows and columns in your {Platform} grid, wi note="30 days free trial. No credit card required." /> -## {ProductName} Supported Browsers +## Next Steps +Start with the [{Platform} Data Grid documentation](data-grid.md), then choose focused guides for [paging](grid/paging.md), [filtering](grid/filtering.md), [editing](grid/editing.md), [selection](grid/selection.md), or [virtualization](grid/virtualization.md). + +## API References +Use the for the complete list of supported API members and configuration options. + +## Additional Resources +Review the [{Platform} List documentation](list.md), [{Platform} Tree Grid documentation](tree-grid.md), and [accessibility guidance](interactivity/accessibility-compliance.md) when selecting and configuring a data presentation component. + +### {ProductName} Supported Browsers The {Platform} Data Grid is supported on all modern web browsers, including: -## {ProductName} Support Options +### {ProductName} Support Options There are multiple options to get access to our award-winning support at Infragistics for the {Platform} product. @@ -312,11 +323,11 @@ There are multiple options to get access to our award-winning support at Infragi - Learn from the {Platform} Reference Applications -## {ProductName} Trial License and Commercial +### {ProductName} Trial License and Commercial

    {ProductName} is a commercially licensed product available via a subscription model. You can try the {ProductName} product for free when you register for a 30-day trial. When you are done with your Trial Period, you can purchase a license from our web site or by calling sales in your region.

    -## Frequently Asked Questions +### Frequently Asked Questions Why should I choose the Infragistics {ProductName} Data Grid?