diff --git a/.claude/skills/igniteui-doc-topics/SKILL.md b/.claude/skills/igniteui-doc-topics/SKILL.md new file mode 100644 index 0000000000..3a3e5e6fe2 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/SKILL.md @@ -0,0 +1,146 @@ +--- +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`. + +### Category/index topics are a separate blueprint + +Do not apply the component-topic blueprint to a category or index page. A category page is a +reference/navigation map, not a composite component page. Its opening should be a short title and +definition, followed directly by **Types** or **Members**. Do **not** add the component-only +`Overview`, `### When to Use`, `### When Not to Use`, `Live Demo`, `Getting Started`, `Usage`, +`Best Practices`, `Properties`, `Accessibility`, or `Troubleshooting` sections to the category +introduction. Put selection guidance in the one-line definition or in the relevant type/member +entry, and put a verified sample inside that entry when one exists. Finish with `Next Steps`, +`API References`, and `Additional Resources` as applicable. + +## 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..41a0d9433d --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/audit-rubric.md @@ -0,0 +1,164 @@ +# 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 + +### Category/index exception +Classify the topic before applying the checks below. A category/index page is evaluated against the +category blueprint in `house-style.md`, not the component-topic checklist. Do not report missing +component sections such as `Overview`, `Live Demo`, `Getting Started`, `Usage`, or `Accessibility` +when the page is correctly structured as `Types/Members` → optional `Key Features` → `Next Steps` / +`API References` / `Additional Resources`. Report a component section appearing in the category +introduction as information-architecture drift instead. + +### 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..39a6667ac8 --- /dev/null +++ b/.claude/skills/igniteui-doc-topics/references/house-style.md @@ -0,0 +1,336 @@ +# 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 + one-line definition → **Types / Members** (identical micro-structure per entry: one-line +definition + link + small verified `` when available) → *Key Features* (cond.) → +**Next Steps / API References / Additional Resources**. + +Category pages do **not** use the component-topic sections `Overview`, `When to Use`, `When Not to +Use`, `Live Demo`, `Getting Started`, `Usage`, `Best Practices`, `Properties`, `Accessibility`, or +`Troubleshooting` as an introductory sequence. Those sections describe one component and create the +wrong information architecture for a category map. Selection guidance belongs in the category +definition or in the relevant type/member entry; a demo belongs inside the entry it demonstrates. + +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. 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/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/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 ` ``` -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. diff --git a/docs/angular/src/content/en/components/checkbox.mdx b/docs/angular/src/content/en/components/checkbox.mdx index 0f0660d65e..6650788bfa 100644 --- a/docs/angular/src/content/en/components/checkbox.mdx +++ b/docs/angular/src/content/en/components/checkbox.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 Checkbox Component Overview +# Checkbox Component -
Angular Checkbox is an extension of the standard HTML input type checkbox, providing similar functionality, only enhanced with things like animations and Material Design styling. It enables users to choose one or several predefined options, mostly in forms and surveys. -The Ignite UI for Angular Checkbox component is a selection control that allows users to make a binary choice for a certain condition. It behaves similarly to the native browser checkbox. Some of the features it offers are styling options, themes, checked, unchecked, and indeterminate states, and others. -
+## Overview -## Angular Checkbox Example +The Ignite UI for Angular Checkbox component is a selection control that allows users to make a binary choice for a certain condition. It behaves similarly to the native browser checkbox, with checked, unchecked, and indeterminate states. + +### When to Use + +Use the checkbox for binary or multi-select choices in forms, filters, or task lists, including a parent "select all" control that can show an indeterminate state. + +### When Not to Use + +When only one option can be selected from a small set, use a group instead of checkboxes. + +## Live Demo See the checkbox in action in the following Angular Checkbox example below. -
+## Anatomy + +{/* TODO: add an annotated screenshot of the checkbox indicator, label, and indeterminate state. */} + +The checkbox consists of an interactive indicator and an optional label. It can represent checked, unchecked, and indeterminate states. -## Getting Started with Ignite UI for Angular Checkbox +```text +Checkbox +├── checkbox indicator +└── optional label +``` + +## Getting Started To get started with the Ignite UI for Angular Checkbox component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: @@ -77,7 +95,7 @@ export class HomeComponent {} Now that you have the Ignite UI for Angular Checkbox module or component imported, you can start using the `igx-checkbox` component. -## Using the Angular Checkbox Component +## Usage To make the checkbox in the demo, add the following code inside the component template: @@ -87,7 +105,7 @@ To make the checkbox in the demo, add the following code inside the component te ``` -### Checkbox properties +### Properties Overview Let's enhance the code above by binding the checkbox properties to some data. Say, we have an array of task objects, each having two properties: description and done. You can bind the checkbox component property to the underlying task object done property. Analogically, you can bind the property to description. Optionally, you can also bind the event and add some custom logic in the provided event handler method. @@ -144,7 +162,7 @@ You can position the label using the checkbox's property: @@ -226,6 +244,27 @@ public toggleAll() { After all that is done, our application should look like this: +## Best Practices + +- Use a visible label that describes the option and keep related checkboxes together. +- Use the indeterminate state only when the selection represents a partially selected group. +- Use a radio group when users must choose exactly one option. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | See API reference | See API reference | Gets or sets whether the checkbox is checked. | +| | See API reference | See API reference | Associates a value with the checkbox. | +| | See API reference | See API reference | Positions the label before or after the checkbox. | +| | See API reference | See API reference | Displays the partially selected state. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| | See API reference | Emitted when the checkbox value changes. | + ## Styling ### Checkbox Theme Property Map @@ -322,19 +361,37 @@ At the end your checkbox should look like this:
+## Accessibility + +### Keyboard Interaction + +Use `Tab` to reach the checkbox and `Space` to toggle its checked state. + +### Screen Readers / ARIA + +Provide a visible label or an accessible name. The checked, unchecked, and indeterminate states must remain understandable without relying on color alone. + +### Accessibility Compliance + +The conformance target must be verified against the product accessibility statement before making a compliance claim. + +## Troubleshooting + +### Why does the master checkbox not show a partial state? + +Set the `indeterminate` property when only some child options are selected, and update it whenever the child selection changes. + ## 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/chip.mdx b/docs/angular/src/content/en/components/chip.mdx index c23e2dd8aa..fc02b65e79 100644 --- a/docs/angular/src/content/en/components/chip.mdx +++ b/docs/angular/src/content/en/components/chip.mdx @@ -22,17 +22,39 @@ import arrowLeftKey from '../images/chip/arrow_left_key.gif'; import arrowRightKey from '../images/chip/arrow_right_key.gif'; import spaceKey from '../images/chip/space_key.gif'; -# Angular Chip Component Overview +# Chip Component - is a visual element that displays information in an oval container. The component has various properties - it can be templated, deleted, and selected. Multiple chips can be reordered and visually connected to each other, using the chip area as a container. + is a visual element that displays information in an oval container. The component has various properties — it can be templated, deleted, and selected. Multiple chips can be reordered and visually connected to each other, using the chip area as a container. -## Angular Chip Example +## Overview + +### When to Use + +Use a chip to represent a compact, removable, or selectable piece of input, attribute, or filter — tags, selected filters, or contact entries. + +### When Not to Use + +For a persistent, non-removable status indicator, use the component instead. + +## Live Demo -
+## Anatomy + +{/* TODO: add an annotated screenshot of the chip label, prefix, selection icon, and remove icon. */} -## Getting Started with Ignite UI for Angular Chip +The chip is a compact interactive element that can contain a label, projected content, prefix content, selection behavior, and an optional remove action. + +```text +Chip +├── optional prefix content +├── label or projected content +├── optional selection icon +└── optional remove button +``` + +## Getting Started To get started with the Ignite UI for Angular Chip component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: @@ -90,7 +112,7 @@ export class HomeComponent { Now that you have the Ignite UI for Angular Chips module or directives imported, you can start using the `igx-chip` component. -## Using the Angular Chip Component +## Usage The has an input property so that the different chip instances can be easily distinguished. If an is not provided, it will be automatically generated. @@ -100,7 +122,7 @@ The has an ``` -## Variants +### Variants The Angular chip supports several pre-defined stylistic variants. You can change the variant by assigning one of the supported values - `primary`, `info`, `success`, `warning`, or `danger` to the input property. @@ -345,7 +367,7 @@ If everything went well, you should see this in your browser: -## Chip Area +### Chip Area The is used when handling more complex scenarios that require interaction between chips (dragging, selection, navigation, etc.). @@ -499,6 +521,31 @@ If everything's set up correctly, you should see this in your browser: +## Best Practices + +- Use chips for compact values such as tags, filters, or selected items; use a button for a standalone action. +- Provide a clear label and make removal or selection behavior understandable from the surrounding context. +- Use a chips area when users need to navigate or reorder multiple chips. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | See API reference | Auto-generated | Identifies the chip instance. | +| | See API reference | See API reference | Applies a predefined visual variant. | +| | See API reference | See API reference | Enables chip selection. | +| | See API reference | See API reference | Enables the remove action. | +| | See API reference | `false` | Enables dragging for chip reordering. | +| | See API reference | See API reference | Replaces the default selection icon template. | +| | See API reference | See API reference | Replaces the default remove icon template. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| | See API reference | Emitted when the chip's remove action is invoked. | +| | See API reference | Emitted by the chips area when a chip is reordered. | + ## Styling ### Chip Theme Property Map @@ -635,19 +682,37 @@ igx-chip { Learn more about it in the [Size](/display-density) article. -## API +## Accessibility + +### Keyboard Interaction + +Use `Tab` to reach a chip. In a chips area, use the documented arrow-key interactions to move between chips and `Delete` to request removal when removal is enabled. + +### Screen Readers / ARIA + +Provide meaningful chip text and ensure that custom selection and remove icons have accessible names through their surrounding controls. +### Accessibility Compliance + +The conformance target must be verified against the product accessibility statement before making a compliance claim. + +## Troubleshooting + +### Why are chips not reordered? + +Enable dragging on the chips and handle the chips area's reorder event to update the backing collection. + +## API References - - - -## Theming Dependencies +## Dependencies - -## References +## 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/circular-progress.mdx b/docs/angular/src/content/en/components/circular-progress.mdx index 75d51d96a9..e33cce003b 100644 --- a/docs/angular/src/content/en/components/circular-progress.mdx +++ b/docs/angular/src/content/en/components/circular-progress.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 Circular Progress Component Overview +# Circular Progress Component -
-The Ignite UI for Angular Circular Progress Indicator component provides a visual indicator of an application’s process as it changes. The circular indicator updates its appearance as its state changes. -
+The Ignite UI for Angular Circular Progress Indicator component provides a visual indicator of an application's process as it changes. The circular indicator updates its appearance as its state changes. + +## Overview + +### When to Use + +Use the circular progress indicator to show determinate or indeterminate progress of a background task in a compact, circular form. -## Angular Circular Progress Example +### When Not to Use + +When progress should span the full width of its container, use a instead. + +## Live Demo -
+## Anatomy -## Getting Started with Ignite UI for Angular Circular Progress +{/* TODO: add an annotated screenshot of the circular track, progress value, and optional label. */} + +The circular progress indicator displays progress around a circular track. It can show a determinate value or an indeterminate animation. + +```text +Circular progress +├── circular track +├── progress indicator +└── optional value or label +``` + +## Getting Started To get started with the Ignite UI for Angular Circular Progress component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: @@ -77,9 +96,9 @@ export class HomeComponent {} Now that you have the Ignite UI for Angular Progress Bar module or directives imported, you can start using the `igx-circular-bar` component. -## Using the Angular Circular Progress +## Usage -To have a better understanding how everything works, let's create a simple example, like the one in the demo: +To have a better understanding how everything works, create a simple example, like the one in the demo: ```html @@ -238,6 +257,28 @@ After reproducing the steps above, you should get this as a result: +## Best Practices + +- Use determinate progress when the application can calculate the completion value. +- Use indeterminate progress only while the duration is unknown, and provide context about the operation. +- Keep the indicator near the content or action whose progress it represents. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | See API reference | See API reference | Sets the maximum progress value. | +| | See API reference | See API reference | Sets the progress increment used by updates. | +| | See API reference | See API reference | Displays progress without a determinate value. | +| | See API reference | See API reference | Shows or hides the progress text. | +| | See API reference | See API reference | Provides a custom SVG gradient template. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| | See API reference | Emitted when the progress value changes. | +
## Styling @@ -274,9 +315,31 @@ The last step is to **include** the component theme in our application. -## API +## Accessibility -
+### Keyboard Interaction + +The progress indicator is informational and is not normally a keyboard target. Keep focus on the action that started the operation. + +### Screen Readers / ARIA + +Provide a programmatic label and expose progress updates through the surrounding status or live-region pattern when the operation requires announcements. +### Accessibility Compliance + +The conformance target must be verified against the product accessibility statement before making a compliance claim. + +## Troubleshooting + +### Why does the indicator not show progress? + +Use a determinate value together with the component's maximum value, and make sure the value is updated when the operation advances. + +## API References - - + +## Additional Resources + +- [Ignite UI for Angular Forums](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) +- [Ignite UI for Angular GitHub](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/divider.mdx b/docs/angular/src/content/en/components/divider.mdx index b5a8f103cb..c9a6438cd3 100644 --- a/docs/angular/src/content/en/components/divider.mdx +++ b/docs/angular/src/content/en/components/divider.mdx @@ -10,19 +10,38 @@ llms: import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Angular Divider Component Overview +# Divider Component -
The divider component enables users to separate content both horizontally and vertically. -
-## Angular Divider Example +## Overview + +### When to Use + +Use the divider to visually separate groups of content or list items, horizontally or vertically. + +### When Not to Use + +Don't place a divider directly before or after a live sample, code fence, or table — those blocks carry their own separation. + +## Live Demo By default the divider is a solid horizontal line. -## Getting Started with Ignite UI for Angular Divider +## Anatomy + +{/* TODO: add an annotated screenshot showing the divider orientation and inset area. */} + +The divider is a visual separator rendered horizontally by default. Its orientation, line style, and inset can be configured for the surrounding layout. + +```text +Divider +└── separator line +``` + +## Getting Started To get started with the Ignite UI for Angular Divider component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: @@ -69,7 +88,7 @@ export class HomeComponent {} Now that you have the Ignite UI for Angular Divider module or directive imported, you can start using the `igx-divider` component. -## Using the Angular Divider +## Usage ### Vertical Divider @@ -112,13 +131,59 @@ To inset the divider, set the `middle` attribute of the divider to `true` and pr If the value of the `middle` attribute is set to a false value, or if the attribute is omitted altogether, the divider will set in only on the left. +## Best Practices + +- Use a divider to separate related content groups, not as decoration between every element. +- Keep sufficient spacing around the divider so the separation remains visible without relying on color alone. +- Choose the orientation that matches the layout and avoid placing dividers immediately beside live samples or code blocks. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `vertical` | `boolean` | `false` | Renders the divider vertically instead of horizontally. | +| `type` | See API reference | `solid` | Sets the divider line style, such as solid or dashed. | +| `middle` | `boolean` | `false` | Applies the inset from both ends when enabled. | +| `inset` | See API reference | See API reference | Sets the inset amount for the divider. | + +## Styling + +Use the to customize the divider's visual appearance. Keep the divider's contrast and spacing sufficient for the surrounding content. + +### Sass Theming + +The `divider-theme` Sass function is the recommended way to define a reusable divider theme. Use the component properties for orientation, line type, and inset, and use the theme for visual tokens such as color. + +| Approach | What it changes | +| --- | --- | +| `divider-theme` | Generates the divider's themed visual styles. | +| `vertical`, `type`, `middle`, and `inset` | Controls the divider's orientation, line style, and spacing in the layout. | + +## Accessibility + +### Keyboard Interaction + +The divider is decorative and is not normally a keyboard target. + +### Screen Readers / ARIA + +Do not use a divider as the only way to communicate a relationship or grouping. Provide headings or landmarks when the grouping must be announced. + +### Accessibility Compliance + +The conformance target must be verified against the product accessibility statement before making a compliance claim. + +## Troubleshooting + +### Why is the divider not vertical? + +Set the `vertical` property to `true` and ensure that the parent layout provides enough height for the separator. + ## API References -
- - -## Additional Resources -
+## Additional Resources Our community is active and always welcoming to new ideas. diff --git a/docs/angular/src/content/en/components/drop-down-hierarchical-selection.mdx b/docs/angular/src/content/en/components/drop-down-hierarchical-selection.mdx index b9d010639d..1124b0fd81 100644 --- a/docs/angular/src/content/en/components/drop-down-hierarchical-selection.mdx +++ b/docs/angular/src/content/en/components/drop-down-hierarchical-selection.mdx @@ -5,6 +5,7 @@ keywords: Multi-select drop-down, hierarchical selection, ignite ui for angular, license: MIT llms: description: "For the drop-down list we will use the DropDown as well as the ToggleActionDirective to open/close the drop-down." +relatedComponents: [Drop Down, Tree, Tree Grid, Chip] --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; @@ -12,11 +13,38 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Multi-select Hierarchical Drop Down +# Multi-select Hierarchical Drop Down Component The following samples demonstrate how to create a multi-select hierarchical drop-down that allows the user to select single or multiple options from a tree-style hierarchical drop-down list. -## Topic Overview +## Overview + +### When to Use + +Use a multi-select hierarchical Drop Down when users need to choose multiple nodes or rows from a tree-shaped data set while keeping the selected values visible as chips. + +### When Not to Use + +For a flat list of independent choices, use with regular items. For a persistent hierarchy that should remain visible, use or directly. + +## Live Demo + + + +## Anatomy + +{/* TODO: add an annotated screenshot of the trigger, hierarchical list, selected nodes, and chips. */} + +The pattern combines a Drop Down, a hierarchical selection component, and chips that represent selected nodes or rows. + +```text +Multi-select hierarchical Drop Down +├── Drop Down overlay +│ └── Tree or Tree Grid +└── selected Chip collection +``` + +## Getting Started For the drop-down list we will use the as well as the to open/close the drop-down. @@ -24,7 +52,9 @@ To visualize the hierarchical data in the drop-down, you can use either the is used to display the selected items. -## Selection +## Usage + +### Selection To display selected nodes/rows from the list use the by handling the events that notify of selection changes and populate the `selectedNodes` / `selectedRows` array. This can be done by subscribing to the IgxTreeComponent's event and to the IgxTreeGridComponent's event. @@ -32,7 +62,7 @@ To remove the chip from the DOM and deselect the item from the tree/grid, you ha Additionally, a way to prevent the drop-down from closing on chip deletion would be to check the event's composite path for an `igx-chip` node and then cancel the event in the `IgxDropDownComponent`'s event handler. -### Demo +#### Tree selection @@ -42,6 +72,50 @@ Additionally, a way to prevent the drop-down from closing on chip deletion would To display the Dropdown component opened initially, it is recommended to set the open method as a callback of the requestAnimationFrame method. This will ensure that the DOM tree is repainted and all elements are correctly positioned. +## Best Practices + +- Keep the selected chips visible so users can review and remove choices without reopening the hierarchy. +- Use a clear label for the trigger and preserve the hierarchy when displaying related options. +- Prevent the Drop Down from closing when a chip is removed if users need to make several selections. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| See generated API reference | See generated API reference | See generated API reference | The complete property table is generated from the typed component APIs. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| | See API reference | Reports changes to selected tree nodes. | +| | See API reference | Reports changes to selected tree-grid rows. | +| | See API reference | Reports removal of a selected chip. | + +## Styling + +Style the Drop Down, hierarchy, and Chip components through their respective component themes. Keep selected chips and the hierarchy visually distinct from the trigger and surrounding content. + +## Accessibility + +### Keyboard Interaction + +Preserve keyboard navigation for the Drop Down and the nested Tree or Tree Grid, and ensure selected chips can be reached and removed with the keyboard. + +### Screen Readers / ARIA + +Provide an accessible name for the trigger and ensure that selected values are available as text, not only through color or visual position. + +### Accessibility Compliance + +Verify hierarchical navigation, selection announcements, focus return, and contrast in the application; this topic does not make a product-level WCAG conformance claim. + +## Troubleshooting + +### Why does the Drop Down close when I remove a chip? + +Handle the Drop Down `closing` event and cancel it when the event's composite path contains the removable chip. + ## API References - - @@ -49,16 +123,14 @@ To display the Dropdown component opened initially, it is recommended to set the - - - -## Additional Resources -
+## Additional Resources - [Drop Down overview](/drop-down) - [Chip overview](/chip) - [Tree overview](/tree) - [Tree Grid overview](/treegrid/tree-grid) -
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/drop-down-virtual.mdx b/docs/angular/src/content/en/components/drop-down-virtual.mdx index 093eba6242..50e7d8f947 100644 --- a/docs/angular/src/content/en/components/drop-down-virtual.mdx +++ b/docs/angular/src/content/en/components/drop-down-virtual.mdx @@ -5,21 +5,47 @@ keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI w license: MIT llms: description: "The Ignite UI for Angular Drop Down component can fully integrate with the IgxForOf directive in order to display a very large list of items for its selection." +relatedComponents: [Drop Down] --- 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'; -# Virtual Drop Down +# Virtual Drop Down Component The Ignite UI for Angular Drop Down component can fully integrate with the [`IgxForOf`](/for-of) directive in order to display a very large list of items for its selection. -## Angular Virtual Drop Down Example +## Overview + +### When to Use + +Use a virtual Drop Down when a selectable list is large enough that rendering every item at once would affect performance. + +### When Not to Use + +For a small list, use the standard without virtualization; it is simpler to configure and maintain. + +## Live Demo -
+## Anatomy + +{/* TODO: add an annotated screenshot of the virtual container, visible items, and scrollbar. */} + +The virtual Drop Down renders a fixed-size viewport and reuses item views as the user scrolls through the collection. + +```text +Virtual Drop Down +├── fixed-size viewport +├── virtualized item collection +└── visible drop-down items +``` + +## Getting Started + +Use the standard Drop Down setup, then import and configure the directive for the item collection. ## Usage @@ -136,7 +162,7 @@ The last part of the configuration is to set `overflow: hidden` to the wrapping } ``` -## Remote Data +### Remote Data The `igx-drop-down` supports loading chunks of remote data using the `*igxFor` structural directive. The configuration is similar to the one with local items, the main difference being how data chunks are loaded. @@ -263,6 +289,48 @@ The result of the above configuration is a drop-down that dynamically loads the
+## Best Practices + +- Provide both a stable item `value` and its data-set `index` to every virtualized item. +- Keep `containerSize` and `itemSize` accurate so scrolling and item reuse remain aligned. +- Use unique item values and use `isHeader` instead of item groups when the list is virtualized. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| See generated API reference | See generated API reference | See generated API reference | The complete property table is generated from the typed API source. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| | See API reference | Emitted when another virtualized data chunk must be loaded. | + +## Styling + +Set `overflow: hidden` on the virtualized wrapper to prevent a second scrollbar from appearing. + +## Accessibility + +### Keyboard Interaction + +Use the Drop Down keyboard navigation to move through visible options while the virtual viewport loads items as needed. + +### Screen Readers / ARIA + +Ensure every virtualized item has a meaningful label and stable value. Do not rely on the visible position alone to identify an option. + +### Accessibility Compliance + +Verify focus management, announced selection, and contrast in the application; this topic does not make a product-level WCAG conformance claim. + +## Troubleshooting + +### Why do items lose their selection while scrolling? + +Pass a unique `value` and the data-set `index` to every `igx-drop-down-item`, and use the data-set index when calling `setSelectedItem`. + ## Notes and Limitations Using the drop-down with a virtualized list of items enforces some limitations. Please, be aware of the following when trying to set up a drop-down list using `*igxFor`: diff --git a/docs/angular/src/content/en/components/drop-down.mdx b/docs/angular/src/content/en/components/drop-down.mdx index c42a2f5547..59864ff84c 100644 --- a/docs/angular/src/content/en/components/drop-down.mdx +++ b/docs/angular/src/content/en/components/drop-down.mdx @@ -5,27 +5,49 @@ keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI w license: MIT llms: description: "The Ignite UI for Angular Drop Down is a component, which displays a toggleable list of predefined values and allows users to easily select a single option item with a click." +relatedComponents: [Combo, Select] --- 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 Drop Down Component Overview +# Drop Down Component
The Ignite UI for Angular Drop Down is a component, which displays a toggleable list of predefined values and allows users to easily select a single option item with a click. It can be quickly configured to act as a drop down menu or you can simply use it to deliver more useful visual information by grouping data. With grouping you can use both flat and hierarchical data. Drop Down component allows declarative binding, which makes it possible for you to embed additional content and links. This also leaves room for further UI customization and styling of the Angular drop down list appearance. In addition to this, it is packed with key features like keyboard dropdown navigation and virtualization.
-## Angular Drop Down Example +## Overview + +### When to Use + +Use the Drop Down to present predefined options from a button or another trigger. Use grouping, templating, or virtualization when the list needs additional structure or contains many items. + +### When Not to Use + +When users need to type and filter while selecting, use . For a short list that remains visible in a form, use . + +## Live Demo This Angular drop down example demonstrates the basic functionalities of a drop down list. Click on it to expand the preset options, select an item, and then close the drop down. -
+## Anatomy + +{/* TODO: add an annotated screenshot of the trigger, overlay, groups, and items. */} -## Getting Started with Ignite UI for Angular Drop Down +The Drop Down consists of an overlay container with selectable items and optional groups, headers, prefixes, suffixes, or custom content. + +```text +Drop Down +├── trigger +├── overlay container +└── drop-down items and optional groups +``` + +## Getting Started To get started with the Ignite UI for Angular Drop Down component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: @@ -90,7 +112,7 @@ export class HomeComponent {} Now that you have the Ignite UI for Angular Drop Down module or directives imported, you can start using the `igx-drop-down` component. -## Using the Angular Drop Down +## Usage ### Add Drop Down @@ -120,7 +142,7 @@ export class MyDropDownComponent { } ``` -## More Angular Drop Down Examples +### Selection and Grouping The default demo shows the use of a toggleable Drop Down List in Angular that lets end-users expand all predefined items and opt for one of them. Check out the following example and see the Angular Drop Down list in action. @@ -494,6 +516,37 @@ When the `allowItemsFocus` property is enabled, the drop down items gain tab ind ``` +## Best Practices + +- Use a clear trigger label and keep the selected value visible after the list closes. +- Group related items and disable unavailable choices instead of removing important context. +- Use virtualization for large collections and provide unique item values when selection depends on identity. +- Use a menu pattern for actions; use a selection control when the user is choosing a value. + +## Properties + +The complete property list is generated from the typed API reference. The table below is reserved for the component's primary properties and must not be treated as an exhaustive API list. + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `boolean` | `false` | Determines whether drop-down items can receive focus. | +| | See API reference | See API reference | Gets the currently selected item. | +| | See API reference | See API reference | Gets the items currently available in the drop-down. | + +## Methods + +| Name | Parameters | Description | +| --- | --- | --- | +| | See API reference | Sets the selected item programmatically. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| | See API reference | Emitted before the drop-down opens. | +| | See API reference | Emitted before the drop-down closes. | +| | See API reference | Emitted when the selection is about to change. | + ## Styling ### Dropdown Theme Property Map @@ -553,7 +606,29 @@ The last step is to pass the custom drop-down theme: -
+## Accessibility + +### Keyboard Interaction + +Use the trigger to open the Drop Down, then use the arrow keys to move between items, `Enter` or `Space` to select an item, and `Escape` to close it. + +### Screen Readers / ARIA + +Give the trigger an accessible name and ensure that item labels communicate their purpose. Do not rely on color alone to communicate selection or disabled state. + +### Accessibility Compliance + +Verify focus management, announced selection, and contrast in the application; this topic does not make a product-level WCAG conformance claim. + +## Troubleshooting + +### Why does the Drop Down not open? + +Ensure the trigger uses the Drop Down toggle and item-navigation directives and that the template reference points to the intended Drop Down instance. + +### Why is the selected item not preserved? + +Provide a unique item value and use the Drop Down selection APIs consistently. For menu behavior, cancel the selection-changing event intentionally because menu items are not meant to preserve selection. ## API References - @@ -563,7 +638,7 @@ The last step is to pass the custom drop-down theme: - - - -## Theming Dependencies +## Dependencies - 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 7618ee456a..b2d00f04fb 100644 --- a/docs/angular/src/content/en/components/grids-and-lists.mdx +++ b/docs/angular/src/content/en/components/grids-and-lists.mdx @@ -1,10 +1,10 @@ --- -title: Angular Grids & Tables | Fastest Angular UI Grid | Infragistics -description: Looking for fast angular grids and tables? Ignite UI for Angular provides a complete library of Angular-native, Material-based UI data grids and tables. Find more. +title: Angular Grids and Lists | Ignite UI for Angular +description: Ignite UI for Angular provides data grids, lists, and related components for displaying, navigating, editing, and analyzing structured data. keywords: angular data grid, infragistics, infragistics.com license: commercial llms: - description: "Ignite UI for Angular provides a complete library of Angular-native, Material-based UI components, including the world’s fastest virtualized Angular data grid." + description: "Ignite UI for Angular provides data grids, lists, and related components for displaying, navigating, editing, and analyzing structured data." --- import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; @@ -18,23 +18,22 @@ import FeatureList from 'docs-template/components/mdx/FeatureList.astro'; [//]: # (
) -# The Fastest Angular Data Grid -Ignite UI for Angular provides a complete library of Angular-native, Material-based UI components, including the world’s fastest virtualized Angular data grid. +# Grids and Lists +Ignite UI for Angular provides components for displaying, navigating, editing, and analyzing structured data in Angular applications. +## Types +Use grids and lists to scan, compare, search, or manage collections of related records. Choose a data grid for tabular data, a list for a one-dimensional collection, and a tree grid for hierarchical rows. -## Angular Grid Example -In this angular 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. +### Angular Data Grid +Display tabular data with column-based operations such as sorting, filtering, editing, grouping, summaries, selection, and export. See the [Angular Data Grid documentation](/grid/grid). - + +### Angular List +Present a one-dimensional collection of items when users need to browse or select records without a column layout. See the [Angular List documentation](/list). -## What is an Angular Data Grid? - -An Angular 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 Angular 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. - -## Why Use an Angular Data Grid? - -Angular 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. +### Angular Tree Grid +Present hierarchical data in rows and columns when users need to expand, collapse, and work with parent-child relationships. See the [Angular Tree Grid documentation](/tree-grid). ## Key Features @@ -61,7 +60,7 @@ This example demonstrates a few of the data grid’s key features: - + ### 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 diff --git a/docs/angular/src/content/en/components/inputs/color-editor.mdx b/docs/angular/src/content/en/components/inputs/color-editor.mdx index 1d885f8a2f..3e9d35818e 100644 --- a/docs/angular/src/content/en/components/inputs/color-editor.mdx +++ b/docs/angular/src/content/en/components/inputs/color-editor.mdx @@ -12,15 +12,36 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import Badge from 'igniteui-astro-components/components/mdx/Badge.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Angular Color Editor Overview +# Color Editor Component The Ignite UI for Angular 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). -## Angular Color Editor Example +## Overview + +### When to Use + +Use the Color Editor when users need to choose or fine-tune a color using visual controls and editable color values. + +### When Not to Use + +Use a simpler color input when users only need to choose from a small, fixed set of predefined colors. + +## Live Demo
+## Anatomy + +The Color Editor combines a color preview, selection surface, and controls for entering or adjusting a color value. + +```text +Color Editor +├── color preview/selection surface +├── color value controls +└── optional actions +``` + ## Dependencies First, you need to install the Ignite UI for Angular by running the following command: @@ -32,6 +53,17 @@ npm install igniteui-angular-inputs Before using the , you need to register the following modules as follows: +```ts +import { IgcColorEditorModule } from "igniteui-angular-inputs"; + +@NgModule({ + imports: [ + IgcColorEditorModule + ] +}) +export class AppModule {} +``` + ## Usage The simplest way to start using the is as follows: @@ -43,13 +75,6 @@ The simplest way to start using the is as follows ``` -## Binding to events - -The Color Editor component raises the following events: - -- valueChanged -- valueChanging - ```ts @ViewChild("colorEditor", { static: true } ) private colorEditor: IgxColorEditorComponent @@ -66,6 +91,54 @@ public onValueChanged = (e: any) => {
+## Best Practices + +- Provide a visible label and a clear way to confirm or cancel a color change. +- Use the editor for detailed color selection; use a simpler color input for constrained choices. +- Do not communicate color meaning through color alone. + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| `value` | `string` | Gets or sets the currently selected color value. | + +The Color Editor API may expose additional platform-specific members. Use the platform-specific API reference below for the complete list rather than assuming that every member is shared across platforms. + +## Events + +| Name | Description | +| --- | --- | +| `valueChanged` | Fires after the selected color value changes. | +| `valueChanging` | Fires while the selected color value is changing. | + +## Styling + +The Color Editor does not currently document component-specific CSS parts in this topic. Style the host element or its containing layout without overriding the editor's interaction states. + +```css +igc-color-editor { + max-width: 320px; + width: 100%; +} +``` + +Keep sufficient space for the color surface, sliders, and value controls. Preserve visible focus indicators and do not use color alone to communicate the selected value or its meaning. + +## Accessibility + +### Keyboard Interaction + +Ensure users can reach every color input and action with the keyboard and can identify the current color value without relying on color perception alone. + +### Screen Readers / ARIA + +Provide a visible label or accessible name for the editor and ensure the selected color has a text representation such as a value or format. + +### Accessibility Compliance + +Verify keyboard operation, focus visibility, text alternatives, and contrast in the application; this topic does not make a product-level WCAG conformance claim. + ## API References
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? diff --git a/docs/xplat/src/content/en/components/inputs/badge.mdx b/docs/xplat/src/content/en/components/inputs/badge.mdx index c142ef717d..83f9d2eb68 100644 --- a/docs/xplat/src/content/en/components/inputs/badge.mdx +++ b/docs/xplat/src/content/en/components/inputs/badge.mdx @@ -1,41 +1,58 @@ --- title: "{Platform} Badge | Infragistics" -description: Infragistics' {Platform} Badge component allows you to display content in a predefined style to decorate other components anywhere in an application. +description: Use the {Platform} Badge to display status indicators — counts, labels, or dot notifications — on avatars, icons, and navigation items. keywords: "{Platform}, UI controls, web widgets, UI widgets, Web Components, {Platform} Badge Components, Infragistics" license: MIT mentionedTypes: ["Badge"] llms: - description: "The {ProductName} Badge is a component used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed." + description: "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." --- 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'; -# {Platform} Badge Overview +# Badge Component -The {ProductName} 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. +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. -## {Platform} 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 `info` — on a list item or card. +- Signal new activity with a minimal dot when the exact count is not relevant. + +### When Not to Use + +- When the indicator must be interactive (clickable or dismissible) — use a instead. +- When you need a standalone label with its own layout — use a chip or tag component. + +## Live Demo +## Anatomy - +The Badge consists of a host element that renders the badge value or slotted content. -## Usage +```text +Badge +└── value or slotted label/content +``` +## Getting Started - -First, you need to install the {ProductName} by running the following command: +Install the {Platform} by running the following command: ```cmd npm install {PackageWebComponents} ``` -You will then need to import the , its necessary CSS, and register its module, like so: +Import the , its necessary CSS, and register its module: ```ts import { defineComponents, IgcBadgeComponent } from "igniteui-webcomponents"; @@ -44,23 +61,19 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; defineComponents(IgcBadgeComponent); ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. - +For a complete introduction to the {Platform}, read the [**Getting Started**](../general-getting-started.md) topic. - - - -First, you need to the install the corresponding {ProductName} npm package by running the following command: +Install the {Platform} npm package: ```cmd npm install igniteui-react ``` -You will then need to import the and its necessary CSS like so: +Import the and its necessary CSS: ```tsx import { IgrBadge } from 'igniteui-react'; @@ -69,31 +82,27 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; - - - - -Before using the , you need to register it as follows: +Register the in `Program.cs`: ```csharp -// in Program.cs file - builder.Services.AddIgniteUIBlazor(typeof(IgbBadgeModule)); ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Link the stylesheet in **wwwroot/index.html** (Blazor WebAssembly) or **Pages/_Host.cshtml** (Blazor Server): ```razor ``` - +## Usage -The simplest way to start using the is as follows: +### Basic Usage + +Add the badge to your template: @@ -145,11 +154,9 @@ To display a subtle border around the badge, you can set the -## Examples - ### Variants -The {ProductName} badge supports several pre-defined stylistic variants. You can change the variant by assigning one of the supported values - `primary`(default), `info`, `success`, `warning`, or `danger` to the attribute. +The {Platform} badge supports several pre-defined stylistic variants. You can change the variant by assigning one of the supported values - `primary`(default), `info`, `success`, `warning`, or `danger` to the attribute. @@ -214,7 +221,7 @@ The badge component supports `rounded`(default) and `square` shapes. These value ### Dot -The {ProductName} badge component can also render as a minimal dot indicator for notifications by setting its attribute. 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.). +The {Platform} badge component can also render as a minimal dot indicator for notifications by setting its attribute. 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.). @@ -242,27 +249,77 @@ The {ProductName} badge component can also render as a minimal dot indicator for +## 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 variants (`success`, `warning`, `danger`, `info`) to communicate status at a glance. +- Pair the badge with an accessible label on its host element so screen readers announce the count. + +**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 + +The component exposes the following properties. + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `StyleVariant` | `primary` | Sets the semantic style variant of the badge. | +| | `boolean` | `false` | Renders an outlined version of the badge when enabled. | +| | `BadgeShape` | `rounded` | Sets the badge shape to `rounded` or `square`. | +| | `boolean` | `false` | Renders a small dot without badge content when enabled. | ## Styling The component exposes a `base` CSS part that can be used to change all of its style properties. + + ```css igc-badge::part(base) { - --background-color: var(--ig-error-A100); - --border-radius: 2px; + --background-color: var(--ig-error-A100); + --border-radius: 2px; } ``` - +## Accessibility + +The {Platform} Badge renders as an inline element. Ensure its host element carries an accessible label that includes the badge value so assistive technologies can announce it. + +### Keyboard Interaction + +The Badge component itself is non-interactive and does not receive keyboard focus. Keyboard interaction is the responsibility of the host element (e.g. a button or link). + +### Screen Readers / ARIA + +The badge sets `role="status"` through its accessibility internals. It also exposes a dynamic `aria-roledescription` in the form `badge {variant}`, such as `badge success`. + +The badge does not generate an accessible name from its value or slotted content. When the badge communicates a count or status for another control, provide an accessible name or description in the host context. Do not rely on color or the badge alone to communicate important information. + +### Accessibility Compliance + +This topic does not make a product-level WCAG conformance claim. The verified implementation provides a status role and a role description, but the final accessibility result also depends on the host element, its accessible name, color contrast, and surrounding content. +| Criterion | How the component supports it | +| --- | --- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) | The `status` role identifies the badge as a status associated with its surrounding content. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | The component exposes `role="status"` and a variant-based `aria-roledescription`. | +**Your responsibilities:** +- Provide an accessible name or description when the badge value is not clear from its surrounding content. +- Do not use color as the only way to communicate the badge state. +- Keep sufficient contrast when overriding the badge theme or CSS custom properties. ## API References ## Additional Resources -- [{ProductName} **Forums**]({ForumsLink}) -- [{ProductName} **GitHub**]({GithubLink}) +- [{Platform} **Forums**]({ForumsLink}) +- [{Platform} **GitHub**]({GithubLink}) 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 e42064068f..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,15 +13,34 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Button Group Overview +# Button Group Component The {Platform} Button Group component is used to organize 's into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling. -## {Platform} Button Example +## Overview + +### When to Use + +Use the Button Group to organize related actions or mutually exclusive options into one clearly associated control. + +### When Not to Use + +Use a standalone when the action does not belong to a set of related options. + +## Live Demo +## Anatomy + +The Button Group contains related toggle buttons and manages their shared orientation and selection state. + +```text +Button Group +└── toggle buttons +``` + ## Usage @@ -269,6 +288,25 @@ The `--ig-size` CSS custom property can be used to control the size of the butto +## Best Practices + +- Group only related toggle buttons and use a clear selection mode. +- Provide values for toggle buttons when reading or setting `selectedItems`. + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| `disabled` | `boolean` | Disables all buttons in the group. | +| `alignment` | `ContentOrientation` | Sets the group orientation. | +| `selection` | `ButtonGroupSelection` | Controls single or multiple selection. | +| `selectedItems` | `string[]` | Gets or sets the selected button values. | + +## Events + +- `igcSelect` fires when a button is selected. +- `igcDeselect` fires when a button is deselected. + ## Styling The component exposes `group` CSS part that allows us to style the button group container. @@ -276,17 +314,30 @@ Also, the s provide `toggle` CSS part ```css igc-button-group::part(group) { - background-color: var(--ig-primary-500); - padding: 8px; + background-color: var(--ig-primary-500); + padding: 8px; } igc-toggle-button::part(toggle) { - color: var(--ig-secondary-300); + color: var(--ig-secondary-300); } ``` +## Accessibility + +### Keyboard Interaction + +Keep the group reachable with `Tab` and verify that selection can be changed with the keyboard. + +### Screen Readers / ARIA + +Use meaningful labels for each toggle button and ensure the selected state is understandable without color alone. + +### Accessibility Compliance + +Verify focus visibility and contrast in the application; this topic does not make a product-level WCAG conformance claim. ## API References diff --git a/docs/xplat/src/content/en/components/inputs/button.mdx b/docs/xplat/src/content/en/components/inputs/button.mdx index 8ae1a8a54f..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 Overview +# Button Component @@ -26,10 +26,32 @@ The {Platform} Button Component lets you enable clickable elements that trigger -## {Platform} Button Example +## Overview + +### When to Use + +Use the Button component for a clear user action such as submitting a form, confirming a choice, or navigating to a destination. + +### When Not to Use + +Use a when users must choose among related toggle options instead of triggering one standalone action. + +## Live Demo +## Anatomy + +{/* TODO: add an annotated screenshot of the button host, label, icon, and focus state. */} + +The Button renders a native button or link inside the component and projects the button content into it. + +```text +Button +├── native button or anchor +└── projected label and/or icon +``` + ## Usage @@ -457,6 +479,21 @@ Setting the +## Best Practices + +- Use a native button action for commands and a link-style button when the interaction navigates. +- Give icon-only buttons an accessible name and keep labels concise and action-oriented. +- Use one primary action in each context and avoid using color as the only signal for importance. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `type` | `'button' | 'reset' | 'submit'` | `button` | Sets the button behavior. | +| `href` | `string` | — | Renders the button as a link to the specified URL. | +| `disabled` | `boolean` | `false` | Disables interaction with the button. | +| `target` | `string` | — | Sets the browsing context for a link button. | + ## Styling The exposes three CSS parts which we can use for styling: @@ -479,6 +516,26 @@ igc-button::part(base) { +## Accessibility + +### Keyboard Interaction + +Native button hosts are reached with `Tab` and activated with `Enter` or `Space`. Link buttons follow native link keyboard behavior. + +### Screen Readers / ARIA + +Use visible button text or provide an accessible name for icon-only buttons. Preserve the native button or link semantics supplied by the component. + +### Accessibility Compliance + +This topic does not make a product-level WCAG conformance claim. Verify the final result with the surrounding label, focus treatment, and color contrast used by the application. + +## Troubleshooting + +### Why does the button not submit the form? + +Set `type="submit"` and ensure the button is associated with the intended form. + ## API References diff --git a/docs/xplat/src/content/en/components/inputs/checkbox.mdx b/docs/xplat/src/content/en/components/inputs/checkbox.mdx index 06899a5506..c4c5605934 100644 --- a/docs/xplat/src/content/en/components/inputs/checkbox.mdx +++ b/docs/xplat/src/content/en/components/inputs/checkbox.mdx @@ -13,16 +13,36 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Checkbox Overview +# 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. -## Checkbox Example +## Overview + +### When to Use + +Use a checkbox when users can independently select one or more options, including a partially selected group represented by an indeterminate state. + +### When Not to Use + +Use a radio group when users must select exactly one option from a small set. + +## Live Demo +## Anatomy + +The Checkbox combines a native checkbox control, an indicator, and its projected label content. + +```text +Checkbox +├── checkbox control and indicator +└── label +``` + ## Usage At its core, the allows for a choice between selected/unselected state. The default styling is done according to the selection controls specification in the Material Design guidelines. @@ -403,6 +423,25 @@ You can use the and +## Best Practices + +- Use a visible label for every checkbox and group related choices under a meaningful heading. +- Use the indeterminate state only to represent a partial selection. + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| `checked` | `boolean` | Gets or sets the checked state. | +| `indeterminate` | `boolean` | Displays the checkbox in an indeterminate state. | +| `disabled` | `boolean` | Disables interaction. | +| `labelPosition` | `ToggleLabelPosition` | Sets the label position. | +| `value` | `string` | Sets the form value. | + +## Events + +- `igcChange` fires when the checked state changes. + ## Styling The component exposes four CSS parts which we can use for styling: @@ -428,6 +467,19 @@ igc-checkbox::part(control checked)::after { +## Accessibility + +### Keyboard Interaction + +Use `Tab` to move focus to the checkbox and `Space` to toggle it. + +### Screen Readers / ARIA + +Provide a visible label or an equivalent accessible name. The checkbox exposes its checked, disabled, and indeterminate state through native control semantics. + +### Accessibility Compliance + +Verify the surrounding label, focus indicator, and color contrast in the application; this topic does not make a product-level WCAG conformance claim. ## API References diff --git a/docs/xplat/src/content/en/components/inputs/chip.mdx b/docs/xplat/src/content/en/components/inputs/chip.mdx index 54254a55ed..692b921bad 100644 --- a/docs/xplat/src/content/en/components/inputs/chip.mdx +++ b/docs/xplat/src/content/en/components/inputs/chip.mdx @@ -12,15 +12,34 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Chip Overview +# Chip Component {ProductName} Chips help people enter information, make selections, filter content, or trigger actions. -## {Platform} Chip Example +## Overview + +### When to Use + +Use a chip to represent compact values such as tags, filters, selected items, or removable inputs. + +### When Not to Use + +Use a for a standalone action or a badge for a non-interactive status indicator. + +## Live Demo - +## Anatomy + +The Chip provides a content area with optional prefix, suffix, selection, and remove affordances. + +```text +Chip +├── prefix +├── content +└── suffix, selection, or remove affordance +``` ## Usage @@ -307,6 +326,27 @@ We allow the user to choose the size of the b +## Best Practices + +- Keep chip labels short and meaningful. +- Use `removable` only when the user can safely remove the represented value. +- Use `selectable` when selection changes surrounding content or filter state. + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| `disabled` | `boolean` | Disables interaction with the chip. | +| `removable` | `boolean` | Shows the remove affordance. | +| `selectable` | `boolean` | Enables selection. | +| `selected` | `boolean` | Gets or sets the selected state. | +| `variant` | `StyleVariant` | Sets the color variant. | + +## Events + +- `igcRemove` fires when the chip is removed. +- `igcSelect` fires when the chip is selected or deselected. + ## Styling The component exposes a `base`, `prefix`, `suffix` CSS parts that can be used to change all of its style properties. @@ -324,6 +364,20 @@ igc-chip::part(suffix) { +## Accessibility + +### Keyboard Interaction + +Selectable and removable chips must remain reachable and operable with the keyboard. + +### Screen Readers / ARIA + +Provide concise chip content and ensure the chip's purpose is clear from its label and surrounding context. + +### Accessibility Compliance + +Verify focus visibility and accessible names in the application; this topic does not make a product-level WCAG conformance claim. + ## API References ## Additional Resources 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 7da0713303..3fa17aa581 100644 --- a/docs/xplat/src/content/en/components/inputs/circular-progress.mdx +++ b/docs/xplat/src/content/en/components/inputs/circular-progress.mdx @@ -4,185 +4,56 @@ description: Circular Progress Indicator component allows developers to display keywords: "{Platform} Circular Progress, {ProductName}, Infragistics" license: MIT mentionedTypes: ["CircularProgress", "CircularGradient"] -namespace: Infragistics.Controls llms: - description: "The {ProductName} Circular Progress Indicator component provides a visual indicator of an application’s process as it changes." + description: "The {ProductName} Circular Progress Indicator provides a visual indicator of an application's progress." --- -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Circular Progress Component -# {Platform} Circular Progress Overview +The {ProductName} Circular Progress Indicator provides a compact visual representation of determinate or indeterminate progress. -The {ProductName} Circular Progress Indicator component provides a visual indicator of an application’s process as it changes. The circular indicator updates its appearance as its state changes. +## Overview -## {Platform} Circular Progress Example +### When to Use - - -## Usage - - - -First, you need to install the {ProductName} by running the following command: - -```cmd -npm install {PackageWebComponents} -``` - -You will then need to import the , its necessary CSS, and register its module, like so: - -```ts -import {defineComponents, IgcCircularProgressComponent} from 'igniteui-webcomponents'; -import 'igniteui-webcomponents/themes/light/bootstrap.css'; - -defineComponents(IgcCircularProgressComponent); -``` - -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. - - - - +Use circular progress for compact progress feedback. -First, you need to the install the corresponding {ProductName} npm package by running the following command: +### When Not to Use -```cmd -npm install igniteui-react -``` - -You will then need to import the , its necessary CSS, and register its module, like so: - -```tsx -import { IgrCircularProgressModule, IgrCircularProgress } from 'igniteui-react'; -import 'igniteui-webcomponents/themes/light/bootstrap.css'; -IgrCircularProgressModule.register(); -``` - - - - +Use when progress should span the width of its container. -Before using the , you need to register it as follows: +## Live Demo -```csharp -// in Program.cs file - -builder.Services.AddIgniteUIBlazor(typeof(IgbCircularProgressModule)); -``` - -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: - -```razor - -``` - - - -The simplest way to start using the is as follows: - - - -```html - -``` - - - - - -```tsx - -``` - - - - - -```razor - -``` - - - -### Progress Types - -You can set the type of your indicator, using the attribute. There are five types of circular progress indicators - **primary** (default), **error**, **success**, **info**, and **warning**. - - - -```tsx - -``` - - - - - -```html - -``` - - - - - -```razor - -``` - - - -### Indeterminate Progress + -If you want to track a process that is not determined precisely, you can set the property. Also, you can hide the default label of the {ProductName} by setting the property and customize the progress indicator default label via the exposed property. +## Anatomy - +The Circular Progress consists of a circular track, a progress indicator, and an optional label. -```tsx - +```text +Circular Progress +├── track +├── progress indicator +└── label/value ``` - +## Usage ```html - -``` - - - - - -```razor - + ``` -The following sample demonstrates the above configuration: - - - -### Animation Duration - -You can use the property on the component to specify how long the animation cycle should take in milliseconds. - ```tsx - -``` - - - - - -```html - + ``` @@ -190,107 +61,77 @@ You can use the ```razor - + ``` ### Gradient Progress -The progress bar can be customized to use a color gradient instead of a solid color by using the `gradient` slot and the component, which defines the gradient stops. - - - - -For each defined as `gradient` slot of {ProductName} a [SVG stop](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop) element would be created. The values passed as `color`, `offset` and `opacity` would be set as stop-color, offset and stop-opacity of the SVG element without further validations. - - - - -```tsx - - - - - - - - -``` - - +Use elements in the `gradient` slot to customize the indicator. ```html - - - + + ``` - + -```razor - - - - - -``` +## Best Practices - +- Use an indeterminate indicator only when the completion time is unknown. +- For determinate progress, provide meaningful `max` and `value` values. + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| `max` | `number` | Sets the maximum value. | +| `value` | `number` | Sets the current value. | +| `variant` | `StyleVariant` | Sets the visual variant. | +| `indeterminate` | `boolean` | Shows progress without a determinate value. | +| `hideLabel` | `boolean` | Shows or hides the default label. | +| `labelFormat` | `string` | Formats the default label. | ## Styling -The component exposes CSS parts for almost all of its inner elements: - -|Name|Description| -|--|--| -| `svg` | The progress SVG element. | -| `gradient_start` | The progress linear-gradient start color. | -| `gradient_end` | The progress linear-gradient end color. | -| `track` | The progress ring's track area. | -| `fill` | The progress indicator area. | -| `label` | The progress label. | -| `value` | The progress label value. | -| `indeterminate` | The progress indeterminate state. | -| `primary` | The progress indicator primary state. | -| `danger` | The progress indicator error state. | -| `warning` | The progress indicator warning state. | -| `info` | The progress indicator info state. | -| `success` | The progress indicator success state. | - -Using this CSS parts we have almost full control over the Circular Progress styling. +The component exposes CSS parts for its inner elements. ```css - igc-circular-progress { - margin: 20px; --diameter: 50px; } -igc-circular-progress::part(gradient_end), -igc-circular-progress::part(gradient_start) { - stop-color: var(--ig-success-200); -} - igc-circular-progress::part(track) { stroke: var(--ig-gray-400); } - ``` - +## Accessibility + +### Keyboard Interaction +Progress indicators are not interactive and should not receive keyboard focus. + +### Screen Readers / ARIA + +Provide surrounding text or a label that explains what is progressing. + +### Accessibility Compliance + +Verify status text and contrast in the application; this topic does not make a product-level WCAG conformance claim. ## API References - - + + + ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) 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 0eaced0662..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,16 +14,37 @@ import Badge from 'igniteui-astro-components/components/mdx/Badge.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Color Editor Overview +# 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). -## {Platform} Color Editor Example +## Overview + +### When to Use + +Use the Color Editor when users need to choose or fine-tune a color using visual controls and editable color values. + +### When Not to Use + +Use a simpler color input when users only need to choose from a small, fixed set of predefined colors. + +## Live Demo
    +## Anatomy + +The Color Editor combines a color preview, selection surface, and controls for entering or adjusting a color value. + +```text +Color Editor +├── color preview/selection surface +├── color value controls +└── optional actions +``` + ## Dependencies @@ -36,7 +57,7 @@ npm install {PackageInputs} Before using the , you need to register the following modules as follows: - + ```ts import { IgcColorEditorModule } from "igniteui-angular-inputs"; @@ -54,7 +75,7 @@ export class AppModule {} ```ts -import { IgcColorEditorModule, IgcColorEditorComponent } from 'igniteui-webcomponents-inputs'; +import { IgcColorEditorComponent, IgcColorEditorModule } from 'igniteui-webcomponents-inputs'; ModuleManager.register( IgcColorEditorModule @@ -87,7 +108,7 @@ First, add the **IgniteUI.Blazor.Controls** namespace in the **_Imports.razor** @using IgniteUI.Blazor.Controls ``` -The following modules are required when using the Dashboard Tile component: +The following modules are required when using the Color Editor component: ```csharp // in Program.cs file @@ -151,13 +172,6 @@ The simplest way to start using the is as follows ``` -## Binding to events - -The Color Editor component raises the following events: - -- valueChanged -- valueChanging - ```ts @ViewChild("colorEditor", { static: true } ) @@ -201,7 +215,7 @@ this.colorEditor.valueChanged = this.OnValueChanged; ```tsx -public onValueChanged(calendar: IgrColorEditor, e: IgrColorEditorPanelSelectedValueChangedEventArgs) { +public onValueChanged(editor: IgrColorEditor, e: IgrColorEditorPanelSelectedValueChangedEventArgs) { } ``` @@ -212,6 +226,54 @@ public onValueChanged(calendar: IgrColorEditor, e: IgrColorEditorPanelSelectedVa
    +## Best Practices + +- Provide a visible label and a clear way to confirm or cancel a color change. +- Use the editor for detailed color selection; use a simpler color input for constrained choices. +- Do not communicate color meaning through color alone. + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| `value` | `string` | Gets or sets the currently selected color value. | + +The Color Editor API may expose additional platform-specific members. Use the platform-specific API reference below for the complete list rather than assuming that every member is shared across platforms. + +## Events + +| Name | Description | +| --- | --- | +| `valueChanged` | Fires after the selected color value changes. | +| `valueChanging` | Fires while the selected color value is changing. | + +## Styling + +The Color Editor does not currently document component-specific CSS parts in this topic. Style the host element or its containing layout without overriding the editor's interaction states. + +```css +igc-color-editor { + max-width: 320px; + width: 100%; +} +``` + +Keep sufficient space for the color surface, sliders, and value controls. Preserve visible focus indicators and do not use color alone to communicate the selected value or its meaning. + +## Accessibility + +### Keyboard Interaction + +Ensure users can reach every color input and action with the keyboard and can identify the current color value without relying on color perception alone. + +### Screen Readers / ARIA + +Provide a visible label or accessible name for the editor and ensure the selected color has a text representation such as a value or format. + +### Accessibility Compliance + +Verify keyboard operation, focus visibility, text alternatives, and contrast in the application; this topic does not make a product-level WCAG conformance claim. + ## API References
    diff --git a/docs/xplat/src/content/en/components/inputs/dropdown.mdx b/docs/xplat/src/content/en/components/inputs/dropdown.mdx index df2edd4ecd..3e8b3dee13 100644 --- a/docs/xplat/src/content/en/components/inputs/dropdown.mdx +++ b/docs/xplat/src/content/en/components/inputs/dropdown.mdx @@ -6,13 +6,14 @@ license: MIT mentionedTypes: ["Dropdown", "DropdownItem", "DropdownHeader", "DropdownGroup"] llms: description: "Feature-rich, the {Platform} Dropdown list offers out-of-the-box filtering, accessibility, preselected values, flexible data binding, grouping, UI customization, and more." +relatedComponents: [Combo, Select] --- 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'; -# {Platform} Dropdown List Component - Overview +# 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. @@ -20,13 +21,36 @@ The Ignite UI for {Platform} Dropdown component displays an toggle list of prede With our component, you get all the functions and customization options you need for your project – styling customizations, {Platform} Dropdown placement options, templates and ability to change what and how is displayed in the header, footer, body, list, etc. -## {Platform} Dropdown Example +## Overview + +### When to Use + +Use the Dropdown to present predefined options from a trigger. Use grouping, placement, and templating when the list needs additional structure. + +### When Not to Use + +When users need to type and filter while selecting, use . For a short list that remains visible in a form, use . + +## Live Demo The following {Platform} Dropdown List example demonstrates the use of simple interactive {Platform} Dropdown menu in action with three basic options to choose from. See how it works. -## How to use the Dropdown List with {ProductName} +## Anatomy + +{/* TODO: add an annotated screenshot of the trigger, overlay, groups, and items. */} + +The Dropdown consists of an overlay list with selectable items and optional headers, groups, prefixes, and suffixes. + +```text +Dropdown +├── trigger +├── overlay list +└── items and optional groups +``` + +## Getting Started @@ -205,6 +229,38 @@ The and properties. +## Best Practices + +- Use a clear trigger label and keep the selected value visible after the list closes. +- Group related items and disable unavailable choices instead of removing important context. +- Use placement and scroll settings that keep the list visible and connected to its trigger. + +## Properties + +The complete property list is available in the generated API reference. The table below includes the primary properties already documented in this topic. + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | See API reference | `bottom-start` | Sets the preferred position of the Dropdown relative to its target. | +| | `boolean` | See API reference | Allows the placement to flip when there is not enough space. | +| | See API reference | See API reference | Sets the distance between the Dropdown and its target. | +| | `boolean` | See API reference | Keeps the Dropdown open when the user clicks outside it. | +| | `boolean` | See API reference | Keeps the Dropdown open after an item is selected. | + +## Methods + +| Name | Parameters | Description | +| --- | --- | --- | +| | See API reference | Opens the Dropdown. | +| | See API reference | Closes the Dropdown. | +| | See API reference | Selects an item by index or value. | + +## Events + +| Name | Payload | Description | +| --- | --- | --- | +| `Change` | See API reference | Fires when the user selects an item. | + ## Styling You can change the appearance of the Dropdown and its items, by using the exposed CSS parts. The exposes `base` and `list` parts, the exposes `prefix`, `content` and `suffix` parts and the exposes `label` part. @@ -226,6 +282,30 @@ igc-dropdown-group::part(label) { +## Accessibility + +### Keyboard Interaction + +Use the trigger to open the Dropdown, then use the arrow keys to move between items, `Enter` or `Space` to select an item, and `Escape` to close it. + +### Screen Readers / ARIA + +Give the trigger an accessible name and ensure item labels communicate their purpose. Do not rely on color alone to communicate selection or disabled state. + +### Accessibility Compliance + +Verify focus management, announced selection, and contrast in the application; this topic does not make a product-level WCAG conformance claim. + +## Troubleshooting + +### Why does the Dropdown not open? + +Ensure the Dropdown is connected to its target and that the target invokes the component's opening behavior. + +### Why does the Dropdown close after selection? + +Set `keepOpenOnSelect` when the interaction requires multiple selections, or leave the default behavior when the list represents a single choice. + ## API References 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 88eadca959..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,53 +12,41 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Linear Progress Overview +# 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. -## {Platform} Linear Progress Example - - +## Overview +### When to Use +Use linear progress to show determinate or indeterminate progress across the width of a container. -## Usage +### When Not to Use +Use when the available space or design calls for a compact circular indicator. - +## Live Demo + -First, you need to install the {ProductName} by running the following command: -```cmd -npm install {PackageWebComponents} -``` -Before using the , you need to register it as follows: +## Anatomy -```ts -import {defineComponents, IgcLinearProgressComponent} from 'igniteui-webcomponents'; -import 'igniteui-webcomponents/themes/light/bootstrap.css'; +The Linear Progress consists of a horizontal track, a progress indicator, and an optional label. -defineComponents(IgcLinearProgressComponent); +```text +Linear Progress +├── track +├── progress indicator +└── label/value ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. - - - - - +## Usage - -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - You will then need to import the , its necessary CSS, and register its module, like so: ```tsx @@ -83,7 +71,7 @@ Before using the , you need to regis builder.Services.AddIgniteUIBlazor(typeof(IgbLinearProgressModule)); ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: ```razor @@ -212,6 +200,23 @@ You can dynamically change the value of the progress indicator by using external +## Best Practices + +- Use an indeterminate indicator only when the completion time is unknown. +- For determinate progress, provide a meaningful `max` and `value`. +- Keep the label visible unless the surrounding context already communicates the state. + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| `max` | `number` | Sets the maximum value. | +| `value` | `number` | Sets the current value. | +| `variant` | `StyleVariant` | Sets the visual variant. | +| `indeterminate` | `boolean` | Shows progress without a determinate value. | +| `striped` | `boolean` | Shows the striped indicator style. | +| `labelAlign` | `LinearProgressLabelAlign` | Sets the default label position. | + ## Styling The component exposes CSS parts for almost all of its inner elements: @@ -230,11 +235,8 @@ The component exposes CSS parts for | `info` | The progress indicator info state. | | `success` | The progress indicator success state. | -Using this CSS parts we have almost full control of the Linear Progress styling. - - ```css igc-linear-progress::part(track){ background-color: var(--ig-gray-300) @@ -249,6 +251,19 @@ igc-linear-progress::part(label){ } ``` +## Accessibility + +### Keyboard Interaction + +Progress indicators are not interactive and should not receive keyboard focus unless the surrounding experience requires it. + +### Screen Readers / ARIA + +Provide surrounding text or a label that explains what is progressing. Ensure determinate values are meaningful and indeterminate progress is not the only status signal. + +### Accessibility Compliance + +Verify the status text and contrast in the application; this topic does not make a product-level WCAG conformance claim. ## API References diff --git a/docs/xplat/src/content/en/components/layouts/divider.mdx b/docs/xplat/src/content/en/components/layouts/divider.mdx index 53931a2091..c7cd7ac563 100644 --- a/docs/xplat/src/content/en/components/layouts/divider.mdx +++ b/docs/xplat/src/content/en/components/layouts/divider.mdx @@ -12,16 +12,35 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Divider +# 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. -## {Platform} Divider Example +## Overview + +### When to Use + +Use a divider to separate related content groups or list items horizontally or vertically. + +### When Not to Use + +Do not use a divider as the only way to communicate a relationship that should be expressed with headings, labels, or landmarks. + +## Live Demo +## Anatomy + +The Divider renders a single horizontal or vertical rule that separates adjacent content. + +```text +Divider +└── divider line +``` + ## Dependencies @@ -286,14 +305,43 @@ The following sample illustrates how the c -## CSS Variables -### Inset -The `--inset` css variable shrinks the divider by the given amount from the start. If middle is set it will shrink from both sides. +## Best Practices + +- Use dividers to reinforce an existing grouping rather than as the only indicator of structure. +- Keep the divider style and orientation consistent within a layout. + +## Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `vertical` | `boolean` | `false` | Renders a vertical divider. | +| `middle` | `boolean` | `false` | Shrinks the divider from both sides when inset styling is used. | +| `type` | `DividerType` | `solid` | Sets a solid or dashed line. | + +## Styling + +Use the `--inset` and `--color` CSS custom properties to customize the divider's visual appearance. Keep the divider's contrast and spacing sufficient for the surrounding content. + +| Variable | What it changes | +| --- | --- | +| `--inset` | Shrinks the divider from the start, or from both sides when `middle` is enabled. | +| `--color` | Sets the divider line color. | + +Use `vertical`, `type`, and `middle` for component behavior, and reserve these CSS custom properties for visual customization. + +## Accessibility + +### Keyboard Interaction + +The divider is decorative and should not receive keyboard focus. + +### Screen Readers / ARIA -### Color -The `--color` css variable sets the color of the divider. +Do not rely on the divider alone to convey relationships; provide headings, labels, or landmarks where needed. +### Accessibility Compliance +Verify that grouping remains understandable when the divider is unavailable or not perceived; this topic does not make a product-level WCAG conformance claim. ## API References