carbon-components-angular
Version:
Next generation components
515 lines (462 loc) • 20.3 kB
HTML
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>carbon-components-angular documentation</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/x-icon" href="./images/favicon.ico">
<link rel="stylesheet" href="./styles/style.css">
<link rel="stylesheet" href="./styles/dark.css">
<style>
footer.carbon {
position: absolute;
bottom: 0;
width: 100%;
z-index: 9999;
}
#root > div {
/*
* Subtracting the height of the footer to prevent
* overlaying the footer ontop of content
*/
height: calc(100vh - 48px);
}
</style>
</head>
<body>
<script>
// Blocking script to avoid flickering dark mode
// Dark mode toggle button
var useDark = window.matchMedia('(prefers-color-scheme: dark)');
var darkModeState = useDark.matches;
var $darkModeToggleSwitchers = document.querySelectorAll('.dark-mode-switch input');
var $darkModeToggles = document.querySelectorAll('.dark-mode-switch');
var darkModeStateLocal = localStorage.getItem('compodoc_darkmode-state');
function checkToggle(check) {
for (var i = 0; i < $darkModeToggleSwitchers.length; i++) {
$darkModeToggleSwitchers[i].checked = check;
}
}
function toggleDarkMode(state) {
if (window.localStorage) {
localStorage.setItem('compodoc_darkmode-state', state);
}
checkToggle(state);
const hasClass = document.body.classList.contains('dark');
if (state) {
for (var i = 0; i < $darkModeToggles.length; i++) {
$darkModeToggles[i].classList.add('dark');
}
if (!hasClass) {
document.body.classList.add('dark');
}
} else {
for (var i = 0; i < $darkModeToggles.length; i++) {
$darkModeToggles[i].classList.remove('dark');
}
if (hasClass) {
document.body.classList.remove('dark');
}
}
}
useDark.addEventListener('change', function (evt) {
toggleDarkMode(evt.matches);
});
if (darkModeStateLocal) {
darkModeState = darkModeStateLocal === 'true';
}
toggleDarkMode(darkModeState);
</script>
<div class="navbar navbar-default navbar-fixed-top d-md-none p-0">
<div class="d-flex">
<a href="./" class="navbar-brand">carbon-components-angular documentation</a>
<button type="button" class="btn btn-default btn-menu ion-ios-menu" id="btn-menu"></button>
</div>
</div>
<div class="xs-menu menu" id="mobile-menu">
<div id="book-search-input" role="search"><input type="text" placeholder="Type to search"></div> <compodoc-menu></compodoc-menu>
</div>
<div class="container-fluid main">
<div class="row main">
<div class="d-none d-md-block menu">
<compodoc-menu mode="normal"></compodoc-menu>
</div>
<!-- START CONTENT -->
<div class="content getting-started">
<div class="content-data">
<p align="center">
<h1 align="center">Carbon Components Angular</h1>
<p align="center">
An Angular implementation of the Carbon Design System
<br /><br />
<a href="https://github.com/carbon-design-system/carbon-components-angular/actions/workflows/publish.yml">
<img src="https://github.com/carbon-design-system/carbon-components-angular/actions/workflows/publish.yml/badge.svg" />
</a>
<a href="https://www.npmjs.com/package/carbon-components-angular">
<img src="https://img.shields.io/npm/v/carbon-components-angular.svg" />
</a>
<img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
<a href="https://www.netlify.com" target="_blank">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg"/>
</a>
<a href="https://bestpractices.coreinfrastructure.org/projects/5887">
<img src="https://bestpractices.coreinfrastructure.org/projects/5887/badge">
</a>
<a href="https://discord.gg/J7JEUEkTRX">
<img src="https://img.shields.io/discord/689212587170201628?color=5865F2" alt="Chat with us on Discord">
</a>
</p>
</p>
<h3>Getting started</h3>
<p>Assuming we're starting with a new @angular/cli project:</p>
<b>Example :</b><div><pre class="line-numbers"><code class="language-shell">$ npx @angular/cli new my-project --style=scss
$ cd my-project
$ npm i --save carbon-components-angular @carbon/styles @carbon/icons</code></pre></div><p>Next, we need to include carbon styles in <code>src/styles.scss</code>:</p>
<b>Example :</b><div><pre class="line-numbers"><code class="language-scss">@use '@carbon/styles/scss/config' with (
// Use flexbox for grid - stick to CSS Grid or Flexbox
// CSS Grid has become the default grid system in v11
$use-flexbox-grid: true,
// Update path of fonts to exclude tilde, required for vite (Angular 16+)
$font-path: '@ibm/plex'
);
@use '@carbon/styles';
// Import css variables in root
html {
@include styles.theme(styles.$white);
}</code></pre></div><p>Then we need to declare <code>@carbon/icons</code> as a module by creating a <code>module.d.ts</code> file (or use any existing declaration file - has <code>.d.ts</code> suffix) in your src directory:</p>
<b>Example :</b><div><pre class="line-numbers"><code class="language-ts">declare module '@carbon/icons/*';</code></pre></div><p>That's it! Now we can run <code>npm start</code> and start building out our application!</p>
<blockquote>
<p><em>Note:</em> This isn't the only way to bootstrap a <code>carbon-components-angular</code> application, but the combination of <code>@angular/cli</code> and the <code>@carbon/styles</code> scss is our recommended setup.</p>
</blockquote>
<p><a href="https://stackblitz.com/edit/stackblitz-starters-exxkq4?file=src%2Fmain.ts"><img src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" alt="Edit Carbon Components Angular" class="img-responsive"></a></p>
<h3>Support</h3>
<ul>
<li>For general usage questions, or other discussions visit our <a href="https://github.com/carbon-design-system/carbon-components-angular/discussions">Github Discussions</a></li>
<li>For things that are broken or need enhancement, <a href="https://github.com/carbon-design-system/carbon-components-angular/issues/new">open an issue</a></li>
<li>For quick usage questions:<ul>
<li>Join the <a href="https://discord.gg/Wys7J95Mhw">Carbon Design System Discord</a>!</li>
<li>IBMers should use our #carbon-ng Slack channel</li>
</ul>
</li>
</ul>
<p>Angular version support matrix:</p>
<table class="table table-bordered compodoc-table">
<thead>
<tr>
<th>Angular</th>
<th>v3</th>
<th>v4</th>
<th>v5</th>
</tr>
</thead>
<tbody>
<tr>
<td>6</td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
</tr>
<tr>
<td>7</td>
<td>✅</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>8</td>
<td>✅</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>9</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>10</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>11</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>12</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>13</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>14</td>
<td>❌</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>15</td>
<td>❌</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>16</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>17</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>18</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
</tbody>
</table>
<p>Carbon Components Angular version support matrix:</p>
<table class="table table-bordered compodoc-table">
<thead>
<tr>
<th>Carbon Components Angular version</th>
<th>Community support</th>
<th>Active support</th>
</tr>
</thead>
<tbody>
<tr>
<td>v1</td>
<td>❌</td>
<td>❌</td>
</tr>
<tr>
<td>v2</td>
<td>❌</td>
<td>❌</td>
</tr>
<tr>
<td>v3</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>v4</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>v5</td>
<td>✅</td>
<td>✅</td>
</tr>
</tbody>
</table>
<p><strong>Not supported versions: Out of support. We plan to support our latest, and previous release. Beyond that we make no guarantees of continued support - these include v1, v2</strong></p>
<p>How to read this table:</p>
<ul>
<li>Community support: We depend primarily on community issue reports, and contributions to help maintain our components. A version with only community support is especially reliant on contributions, though we will backport small fixes when applicable.</li>
<li>Active support: We will actively maintain and update these versions with new features, new components, bug fixes, and ensure it's compatible with the Carbon Design System and latest Angular versions</li>
</ul>
<h3>Contributing</h3>
<h4>IBMers contributing</h4>
<p><strong>If you are an IBMer</strong>, you must complete the steps at <a href="https://w3.ibm.com/developer/docs/open-source/contributing/">W3 Developer</a> before contributing to any open source projects. See our <a href="https://github.com/carbon-design-system/carbon-components-angular/blob/master/.github/CONTRIBUTING.md">contributing guidelines</a> for more details.</p>
<h4>Quickstart</h4>
<ul>
<li>fork carbon-design-system/carbon-components-angular and clone it locally</li>
<li>run <code>npm install</code> to grab all the dependencies, then <code>npm run storybook</code> to start storybook</li>
<li><strong>if you are adding a component</strong>:<ul>
<li>add a folder with your component code, styles, tests and story under <code>src</code></li>
<li>export your module from <code>index.ts</code></li>
</ul>
</li>
<li><strong>if you are contributing a fix</strong>:<ul>
<li>add your fix, update the documentation as needed</li>
<li>consider adding or modifying a test case to cover the fix</li>
</ul>
</li>
<li>follow the <a href="https://angular.dev/style-guide">Angular style guide</a></li>
<li>be sure to run <code>npm test</code> and <code>npm run lint</code> to make sure the tests and linter pass</li>
<li>submit a PR</li>
</ul>
<h4>Pull request guidelines</h4>
<ul>
<li><strong>Keep changes small and focused.</strong></li>
<li>If you create a pull request and then realize it is not ready to be merged, prepend "WIP: " (For example, WIP: Fixed text overflow in accordion headers.) and assign a WIP label.</li>
<li>Include a description of changes<ul>
<li>attach a screenshot (or a gif!) for design reference if needed</li>
<li>reference the related issue<ul>
<li>"closes #123" or "fixes #123" will close issue #123 once the PR is merged</li>
<li>"issue #123" just references the issue. Only use this if you definitely need the issue to remain open.</li>
</ul>
</li>
<li>@mention any specific other developers that need to be aware of the changes</li>
</ul>
</li>
<li>add the "needs review" label along with any other relevant labels</li>
<li><a href="#">link to code review checklist goes here</a></li>
</ul>
<h4>Issues submission guidelines</h4>
<ul>
<li><strong>One issue per defect</strong> - do not open an issue that spans multiple defects</li>
<li>provide a descriptive title that mentions the component and version the issue covers</li>
<li>provide<ul>
<li>version(s) affected</li>
<li>a description of the issue</li>
<li>steps taken to produce the issue</li>
<li>expected behaviour</li>
<li>current behaviour</li>
<li>screenshots if needed</li>
<li>relevant code snippets</li>
<li>links to application source code or running demo (<a href="https://codesandbox.io/s/angular">Codesandbox is awesome for this!</a>) (including connection/authentication information)</li>
</ul>
</li>
<li>add relevant labels (bug, accessibility, design, discussion, feature, etc)</li>
<li>if you have a fix to contribute, assign yourself, otherwise leave unassigned</li>
</ul>
<h4>npm commands</h4>
<p>To keep our build dependencies local we use npm scripts to run our webpack, gulp, and general build tasks. You should never install webpack or gulp globally as that will likely conflict with our version. You should never need to modify the build process to add a component or story.</p>
<ul>
<li><code>npm run storybook</code> to run storybook (port 6006)</li>
<li><code>npm run build</code> to generate the dist</li>
<li><code>docs:build</code> to build documentation</li>
<li><code>docs:server</code> to build and run the documentation server</li>
<li><code>npm run lint</code> to run tslint</li>
<li><code>npm test</code> to run tests</li>
</ul>
<h3>Resources</h3>
<ul>
<li><a href="https://github.com/carbon-design-system/carbon-components-angular/wiki/Style-guide">Style guide (WIP)</a></li>
<li><a href="https://github.com/carbon-design-system/carbon-components-angular/wiki/Component-API-guidelines">General component API guidelines (WIP)</a></li>
<li><a href="https://angular.io/styleguide">Angular style guide</a></li>
<li>I18N tooling<ul>
<li><a href="https://angular.io/guide/i18n">I18N guide</a></li>
<li><a href="https://github.com/ngx-translate/core">ngx-translate</a></li>
</ul>
</li>
<li>(Angular 2+ doesn't have anything like ngAria, instead here's <a href="http://a11yproject.com/">The A11Y Project</a>, <a href="https://www.w3.org/TR/wai-aria/">WAI-ARIA specs</a>, and <a href="https://www.w3.org/TR/2016/WD-wai-aria-practices-1.1-20160317/">WAI-ARIA Authoring Practices</a>)</li>
<li><a href="https://www.typescriptlang.org/docs/tutorial.html">TypeScript docs</a></li>
</ul>
<h3>Philosophy</h3>
<ul>
<li>Components should be the smallest unit of computation<ul>
<li>Think in terms of pages and applications composed from a multitude of components rather than pages or applications as a single unit of computation</li>
</ul>
</li>
<li>Components should delegate to the consumer whenever possible<ul>
<li>The individual applications should be the single source of truth, and be able to create any UI from our building blocks</li>
</ul>
</li>
<li>Components should do one thing, and do it well<ul>
<li>This does not mean they should be over specialized, but rather focus on providing a single, core experience</li>
</ul>
</li>
<li>Components should NOT maintain more state than absolutely necessary<ul>
<li>Likewise, stateless components should be favored whenever possible</li>
</ul>
</li>
<li>Components should NOT <em>necessarily</em> implement the style guide point-for-point, the guide simply provides guidance on overarching functionality, components should enable that and product specific designs <strong>without</strong> baking in extra functionality</li>
</ul>
<h2>Code of Conduct</h2>
<p>Read our code of conduct <a href="./.github/CODE_OF_CONDUCT.md">here</a></p>
<h2><picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry</h2>
<p>This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing
this package as a dependency you are agreeing to telemetry collection. To opt out, see
<a href="https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection">Opting out of IBM Telemetry data collection</a>.
For more information on the data being collected, please see the
<a href="https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics">IBM Telemetry documentation</a>.</p>
</div><div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
<!-- END CONTENT -->
</div>
</div>
<label class="dark-mode-switch">
<input type="checkbox">
<span class="slider">
<svg class="slider-icon" viewBox="0 0 24 24" fill="none" height="20" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" width="20" xmlns="http://www.w3.org/2000/svg">
<path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"></path>
</svg>
</span>
</label>
<script>
var COMPODOC_CURRENT_PAGE_DEPTH = 0;
var COMPODOC_CURRENT_PAGE_CONTEXT = 'getting-started';
var COMPODOC_CURRENT_PAGE_URL = 'index.html';
var MAX_SEARCH_RESULTS = 15;
</script>
<script>
$darkModeToggleSwitchers = document.querySelectorAll('.dark-mode-switch input');
checkToggle(darkModeState);
if ($darkModeToggleSwitchers.length > 0) {
for (var i = 0; i < $darkModeToggleSwitchers.length; i++) {
$darkModeToggleSwitchers[i].addEventListener('change', function (event) {
darkModeState = !darkModeState;
toggleDarkMode(darkModeState);
});
}
}
</script>
<script src="./js/libs/custom-elements.min.js"></script>
<script src="./js/libs/lit-html.js"></script>
<script src="./js/menu-wc.js" defer></script>
<script nomodule src="./js/menu-wc_es5.js" defer></script>
<script src="./js/libs/bootstrap-native.js"></script>
<script src="./js/libs/es6-shim.min.js"></script>
<script src="./js/libs/EventDispatcher.js"></script>
<script src="./js/libs/promise.min.js"></script>
<script src="./js/libs/zepto.min.js"></script>
<script src="./js/compodoc.js"></script>
<script src="./js/tabs.js"></script>
<script src="./js/menu.js"></script>
<script src="./js/libs/clipboard.min.js"></script>
<script src="./js/libs/prism.js"></script>
<script src="./js/sourceCode.js"></script>
<script src="./js/search/search.js"></script>
<script src="./js/search/lunr.min.js"></script>
<script src="./js/search/search-lunr.js"></script>
<script src="./js/search/search_index.js"></script>
<script src="./js/lazy-load-graphs.js"></script>
<footer class="carbon">
<dds-footer-container key="footer" disable-locale-button="true" size="micro" />
</footer>
<script
key="8"
type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v1/latest/footer.min.js">
</script>
<!-- Storybook override -->
<script>
document.title = "Carbon Components Angular";
</script>
<script
src="//1.www.s81c.com/common/stats/ibm-common.js"
type="text/javascript"
async="async">
</script>
</body>
</html>