개요 • Angular

Angular Aria란?

접근성을 지원하는 컴포넌트를 만드는 일은 간단해 보이지만, W3C 접근성 가이드라인에 맞춰 구현하려면 상당한 노력과 접근성 전문 지식이 필요합니다.

Angular Aria는 일반적인 WAI-ARIA 패턴을 구현한 디렉티브 모음입니다. 이 디렉티브들은 UI 형태를 정하지 않는 헤드리스 방식으로 접근성을 지원하며, 키보드 조작, ARIA 어트리뷰트, 포커스 관리, 스크린 리더 지원을 처리합니다. 개발자는 HTML 구조, CSS 스타일, 비즈니스 로직만 작성하면 됩니다!

설치

활용 예시

툴바 메뉴를 예로 들어보겠습니다. 특정 로직과 연결된 버튼을 한 줄로 나열한 "단순한" UI처럼 보일 수 있습니다. 하지만 접근성에 익숙하지 않다면 키보드 탐색과 스크린 리더 지원 때문에 예상하지 못한 복잡한 문제를 만나게 됩니다.

app.ts

import {Component, signal} from '@angular/core';
import {Toolbar, ToolbarWidget, ToolbarWidgetGroup} from '@angular/aria/toolbar';

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
})
export class App {
  readonly bold = signal(false);
  readonly italic = signal(false);
  readonly underlined = signal(false);
  readonly alignment = signal<'left' | 'center' | 'right'>('left');
}

app.html

<div ngToolbar aria-label="Text Formatting Tools">
  <div class="group">
    <button
      ngToolbarWidget
      value="undo"
      type="button"
      aria-label="undo"
      class="material-symbols-outlined"
      translate="no"
    >
      undo
    </button>

    <button
      ngToolbarWidget
      value="redo"
      type="button"
      aria-label="redo"
      class="material-symbols-outlined"
      translate="no"
    >
      redo
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div class="group">
    <button
      ngToolbarWidget
      value="bold"
      type="button"
      aria-label="bold"
      class="material-symbols-outlined"
      [attr.aria-pressed]="bold()"
      (click)="bold.set(!bold())"
      translate="no"
    >
      format_bold
    </button>

    <button
      ngToolbarWidget
      value="italic"
      type="button"
      aria-label="italic"
      class="material-symbols-outlined"
      [attr.aria-pressed]="italic()"
      (click)="italic.set(!italic())"
      translate="no"
    >
      format_italic
    </button>

    <button
      ngToolbarWidget
      value="underlined"
      type="button"
      aria-label="underlined"
      class="material-symbols-outlined"
      [attr.aria-pressed]="underlined()"
      (click)="underlined.set(!underlined())"
      translate="no"
    >
      format_underlined
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div ngToolbarWidgetGroup role="radiogroup" class="group" aria-label="Text alignment options">
    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align left"
      aria-label="align left"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'left'"
      (click)="alignment.set('left')"
      translate="no"
    >
      format_align_left
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align center"
      aria-label="align center"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'center'"
      (click)="alignment.set('center')"
      translate="no"
    >
      format_align_center
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align right"
      aria-label="align right"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'right'"
      (click)="alignment.set('right')"
      translate="no"
    >
      format_align_right
    </button>
  </div>
</div>

app.css

@import url('https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined');

:host {
  display: flex;
  justify-content: center;
}

[ngToolbar] {
  gap: 1.5rem;
  display: flex;
  padding: 0.5rem 1rem;
  border-radius: 0.5rem;
  background-color: var(--septenary-contrast);
}

.group {
  gap: 0.5rem;
  display: flex;
}

.separator {
  width: 1px;
  align-self: center;
  height: calc(100% - 1rem);
  background-color: var(--quinary-contrast);
}

[ngToolbarWidget] {
  border: none;
  cursor: pointer;
  padding: 0.5rem;
  border-radius: 4px;
  font-size: 1.25rem;
  background-color: transparent;
  color: var(--primary-contrast);
}

[ngToolbarWidget]:hover {
  background-color: color-mix(in srgb, var(--primary-contrast) 10%, transparent);
}

[ngToolbarWidget]:active {
  background-color: color-mix(in srgb, var(--primary-contrast) 15%, transparent);
}

[ngToolbarWidget]:focus {
  outline-offset: -1px;
  outline: 1px solid color-mix(in srgb, var(--hot-pink) 60%, transparent);
}

[ngToolbarWidget][aria-pressed="true"],
[ngToolbarWidget][aria-checked="true"] {
  color: color-mix(in srgb, var(--hot-pink) 80%, var(--primary-contrast));
  background-color: color-mix(in srgb, var(--hot-pink) 10%, transparent);
}

app.ts

import {Component, signal} from '@angular/core';
import {Toolbar, ToolbarWidget, ToolbarWidgetGroup} from '@angular/aria/toolbar';

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
})
export class App {
  readonly bold = signal(false);
  readonly italic = signal(false);
  readonly underlined = signal(false);
  readonly alignment = signal<'left' | 'center' | 'right'>('left');
}

app.html

<div ngToolbar class="material-toolbar" aria-label="Text Formatting Tools">
  <div class="group">
    <button
      ngToolbarWidget
      value="undo"
      type="button"
      aria-label="undo"
      class="material-symbols-outlined"
      translate="no"
    >
      undo
    </button>

    <button
      ngToolbarWidget
      value="redo"
      type="button"
      aria-label="redo"
      class="material-symbols-outlined"
      translate="no"
    >
      redo
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div class="group">
    <button
      ngToolbarWidget
      value="bold"
      type="button"
      aria-label="bold"
      class="material-symbols-outlined"
      [attr.aria-pressed]="bold()"
      (click)="bold.set(!bold())"
      translate="no"
    >
      format_bold
    </button>

    <button
      ngToolbarWidget
      value="italic"
      type="button"
      aria-label="italic"
      class="material-symbols-outlined"
      [attr.aria-pressed]="italic()"
      (click)="italic.set(!italic())"
      translate="no"
    >
      format_italic
    </button>

    <button
      ngToolbarWidget
      value="underlined"
      type="button"
      aria-label="underlined"
      class="material-symbols-outlined"
      [attr.aria-pressed]="underlined()"
      (click)="underlined.set(!underlined())"
      translate="no"
    >
      format_underlined
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div ngToolbarWidgetGroup role="radiogroup" class="group" aria-label="Text alignment options">
    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align left"
      aria-label="align left"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'left'"
      (click)="alignment.set('left')"
      translate="no"
    >
      format_align_left
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align center"
      aria-label="align center"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'center'"
      (click)="alignment.set('center')"
      translate="no"
    >
      format_align_center
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align right"
      aria-label="align right"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'right'"
      (click)="alignment.set('right')"
      translate="no"
    >
      format_align_right
    </button>
  </div>
</div>

app.css

@import url('https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined');

:host {
  display: flex;
  justify-content: center;
}

[ngToolbar] {
  display: flex;
}

[ngToolbarWidget] {
  border: none;
  outline: none;
  cursor: pointer;
  width: 3rem;
  height: 3rem;
  font-size: 1.25rem;
  border-radius: 2rem;
  color: color-mix(in srgb, var(--vivid-pink) 70%, var(--full-contrast));
  background-color: color-mix(in srgb, var(--vivid-pink) 20%, transparent);
  transition:
    width 0.2s ease-in-out,
    background-color 0.15s ease-in-out,
    color 0.15s ease-in-out;
}

[ngToolbarWidget]:focus {
  outline-offset: 2px;
  outline: 2px solid var(--vivid-pink);
}

[ngToolbarWidget]:active,
[ngToolbarWidget][aria-pressed='true'],
[ngToolbarWidget][aria-checked='true'] {
  background-color: color-mix(in srgb, var(--vivid-pink) 80%, var(--full-contrast));
  color: var(--page-background);
}

[ngToolbarWidget][aria-checked='true'] {
  width: 4.5rem;
}

.group {
  display: flex;
  gap: 0.5rem;
}

.separator {
  width: 1px;
  margin: 0 1rem;
  height: calc(100% - 2rem);
  background-color: var(--quinary-contrast);
}

app.ts

import {Component, signal} from '@angular/core';
import {Toolbar, ToolbarWidget, ToolbarWidgetGroup} from '@angular/aria/toolbar';

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
})
export class App {
  readonly bold = signal(false);
  readonly italic = signal(false);
  readonly underlined = signal(false);
  readonly alignment = signal<'left' | 'center' | 'right'>('left');
}

app.html

<div ngToolbar class="retro-toolbar" aria-label="Text Formatting Tools">
  <div class="group">
    <button
      ngToolbarWidget
      value="undo"
      type="button"
      aria-label="undo"
      class="material-symbols-outlined"
      translate="no"
    >
      undo
    </button>

    <button
      ngToolbarWidget
      value="redo"
      type="button"
      aria-label="redo"
      class="material-symbols-outlined"
      translate="no"
    >
      redo
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div class="group">
    <button
      ngToolbarWidget
      value="bold"
      type="button"
      aria-label="bold"
      class="material-symbols-outlined"
      [attr.aria-pressed]="bold()"
      (click)="bold.set(!bold())"
      translate="no"
    >
      format_bold
    </button>

    <button
      ngToolbarWidget
      value="italic"
      type="button"
      aria-label="italic"
      class="material-symbols-outlined"
      [attr.aria-pressed]="italic()"
      (click)="italic.set(!italic())"
      translate="no"
    >
      format_italic
    </button>

    <button
      ngToolbarWidget
      value="underlined"
      type="button"
      aria-label="underlined"
      class="material-symbols-outlined"
      [attr.aria-pressed]="underlined()"
      (click)="underlined.set(!underlined())"
      translate="no"
    >
      format_underlined
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div ngToolbarWidgetGroup role="radiogroup" class="group" aria-label="Text alignment options">
    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align left"
      aria-label="align left"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'left'"
      (click)="alignment.set('left')"
      translate="no"
    >
      format_align_left
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align center"
      aria-label="align center"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'center'"
      (click)="alignment.set('center')"
      translate="no"
    >
      format_align_center
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align right"
      aria-label="align right"
      class="material-symbols-outlined"
      [attr.aria-checked]="alignment() === 'right'"
      (click)="alignment.set('right')"
      translate="no"
    >
      format_align_right
    </button>
  </div>
</div>

app.css

@import url('https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined');

:host {
  display: flex;
  justify-content: center;

  font-family: 'Press Start 2P';
  --retro-button-color: color-mix(in srgb, var(--vivid-pink) 80%, var(--page-background));
  --retro-pressed-tint: #fbfbfb;
  --retro-shadow-light: color-mix(in srgb, var(--retro-button-color) 90%, #fff);
  --retro-shadow-dark: color-mix(in srgb, var(--retro-button-color) 90%, #000);
  --retro-elevated-shadow:
    inset 4px 4px 0px 0px var(--retro-shadow-light),
    inset -4px -4px 0px 0px var(--retro-shadow-dark), 4px 0px 0px 0px var(--tertiary-contrast),
    0px 4px 0px 0px var(--tertiary-contrast), -4px 0px 0px 0px var(--tertiary-contrast),
    0px -4px 0px 0px var(--tertiary-contrast);
  --retro-flat-shadow:
    4px 0px 0px 0px var(--tertiary-contrast), 0px 4px 0px 0px var(--tertiary-contrast),
    -4px 0px 0px 0px var(--tertiary-contrast), 0px -4px 0px 0px var(--tertiary-contrast);
  --retro-clickable-shadow:
    inset 4px 4px 0px 0px var(--retro-shadow-light),
    inset -4px -4px 0px 0px var(--retro-shadow-dark), 4px 0px 0px 0px var(--tertiary-contrast),
    0px 4px 0px 0px var(--tertiary-contrast), -4px 0px 0px 0px var(--tertiary-contrast),
    0px -4px 0px 0px var(--tertiary-contrast), 8px 8px 0px 0px var(--tertiary-contrast);
  --retro-pressed-shadow:
    inset 4px 4px 0px 0px var(--retro-shadow-dark),
    inset -4px -4px 0px 0px var(--retro-shadow-light), 4px 0px 0px 0px var(--tertiary-contrast),
    0px 4px 0px 0px var(--tertiary-contrast), -4px 0px 0px 0px var(--tertiary-contrast),
    0px -4px 0px 0px var(--tertiary-contrast), 0px 0px 0px 0px var(--tertiary-contrast);
}

:host-context(.docs-dark-mode) {
  --retro-pressed-tint: #151417;
}

[ngToolbar] {
  gap: 1.5rem;
  display: flex;
  padding: 1rem;
}

.group {
  gap: 1rem;
  display: flex;
}

.separator {
  width: 1px;
  align-self: center;
  height: calc(100% - 1rem);
  background-color: var(--quinary-contrast);
}

[ngToolbarWidget] {
  border: none;
  outline: none;
  cursor: pointer;
  padding: 0.5rem;
  font-size: 1.25rem;
  color: var(--page-background);

  background-color: var(--retro-button-color);
  box-shadow: var(--retro-clickable-shadow);
  transition:
    transform 0.1s,
    box-shadow 0.1s;
}

[ngToolbarWidget]:focus,
[ngToolbarWidget]:hover {
  transform: translate(1px, 1px);
}

[ngToolbarWidget]:active,
[ngToolbarWidget][aria-pressed='true'],
[ngToolbarWidget][aria-checked='true'] {
  transform: translate(4px, 4px);
  box-shadow: var(--retro-pressed-shadow);
  background-color: color-mix(in srgb, var(--retro-button-color) 60%, var(--retro-pressed-tint));
}

[ngToolbarWidget]:focus {
  outline-offset: 4px;
  outline: 4px dashed var(--retro-button-color);
}

이 예제만 해도 개발자는 다음 사항을 고려해야 합니다.

키보드 탐색: 사용자가 Enter나 Space로 메뉴를 열고, 방향키로 옵션을 탐색하고, Enter로 선택하고, Escape로 닫을 수 있어야 합니다.
스크린 리더: 메뉴의 상태, 옵션의 수, 현재 포커스가 있는 옵션을 안내해야 합니다.
포커스 관리: 트리거와 메뉴 항목 사이에서 포커스가 논리적인 순서로 이동해야 합니다.
오른쪽에서 왼쪽으로 쓰는 언어: 반대 방향으로 탐색할 수 있어야 합니다.

어떤 기능이 포함되어 있나요?

Angular Aria는 일반적인 상호작용 패턴에 대한 디렉티브와 함께 상세한 문서, 동작하는 예제, API 레퍼런스를 제공합니다.

검색과 선택

컴포넌트	설명
자동 완성	사용자가 입력하면 필터링된 추천 항목을 표시하는 텍스트 입력란
리스트박스	키보드 탐색을 지원하는 단일 또는 다중 선택 옵션 목록
선택	키보드 탐색을 지원하는 단일 선택 드롭다운 패턴
다중 선택	선택 결과를 간결하게 표시하는 다중 선택 드롭다운 패턴
콤보박스	텍스트 입력란과 팝업을 연결하는 기본 디렉티브

탐색과 작업 실행

컴포넌트	설명
메뉴	중첩된 하위 메뉴와 키보드 단축키를 지원하는 드롭다운 메뉴
메뉴바	애플리케이션 메뉴를 항상 표시하는 수평 탐색 막대
툴바	논리적인 키보드 탐색을 지원하는 컨트롤 그룹

콘텐츠 구성

컴포넌트	설명
아코디언	여러 개를 개별적으로 펼치거나 한 번에 하나만 펼칠 수 있는 접이식 콘텐츠 패널
탭	자동 또는 수동 활성화 모드를 지원하는 탭 인터페이스
트리	펼치기와 접기 기능을 지원하는 계층형 목록
그리드	셀 단위 키보드 탐색을 지원하는 2차원 데이터 표시

Angular Aria를 사용하기 좋은 경우

Angular Aria는 커스텀 스타일을 적용하면서 WCAG를 준수하는 접근성 있는 상호작용 컴포넌트가 필요할 때 적합합니다. 예를 들면 다음과 같습니다.

디자인 시스템 구축: 팀에서 특정 시각적 기준을 따르는 컴포넌트 라이브러리를 관리하며 접근성 구현이 필요한 경우
기업용 컴포넌트 라이브러리: 조직 내 여러 애플리케이션에서 재사용할 컴포넌트를 만드는 경우
브랜드 고유 요구사항: 스타일이 미리 지정된 컴포넌트 라이브러리로는 쉽게 구현하기 어려운 구체적인 디자인 명세를 따라야 하는 경우

Angular Aria가 적합하지 않은 경우

Angular Aria가 모든 상황에 적합한 것은 아닙니다.

스타일이 미리 지정된 컴포넌트: 커스텀 스타일을 작성하지 않아도 완성된 모습의 컴포넌트가 필요하다면 Angular Material을 사용하세요.
간단한 폼: <button>이나 <input type="radio"> 같은 네이티브 HTML 폼 컨트롤은 간단한 사용 사례에 필요한 접근성을 기본으로 제공합니다.
빠른 프로토타입 제작: 아이디어를 빠르게 검증하려면 스타일이 미리 지정된 컴포넌트 라이브러리를 사용해서 초기 개발 시간을 줄일 수 있습니다.

다음 단계

사이드 내비게이션이나 위 목록에서 컴포넌트를 살펴보세요. 툴바부터 시작하면 Angular Aria 디렉티브가 어떻게 동작하는지 완전한 예제로 확인할 수 있습니다!

Angular Aria

Angular Aria란?

설치

npm

yarn

pnpm

bun

활용 예시

app.ts

app.html

app.css

app.ts

app.html

app.css

app.ts

app.html

app.css

어떤 기능이 포함되어 있나요?

검색과 선택

탐색과 작업 실행

콘텐츠 구성

Angular Aria를 사용하기 좋은 경우

Angular Aria가 적합하지 않은 경우

다음 단계