carbon-custom-elements
Advanced tools
A Carbon Design System variant that's as easy to use as native HTML elements, with no framework tax, no framework silo.
A Carbon Design System variant that's as easy to use as native HTML elements, with no framework tax, no framework silo.
Carbon is an open-source design system built by IBM. With the IBM Design Language as its foundation, the system consists of working code, design tools and resources, human interface guidelines, and a vibrant community of contributors.
carbon-custom-elementscarbon-custom-elements is a variant of Carbon Design System with Custom Elements v1 and Shadow DOM v1 specs.
Has been experimenting with enthusiasm, and now has a stable version.
The effort stems from https://github.com/carbon-design-system/issue-tracking/issues/121. If you are interested in this project, adding 👍 to the description of that GH issue, or even contributing, will be greatly appreciated!
To install carbon-custom-elements in your project, you will need to run the
following command using npm:
npm install -S carbon-custom-elements carbon-components lit-html lit-element
If you prefer Yarn, use the following command instead:
yarn add carbon-custom-elements carbon-components lit-html lit-element
Our example at CodeSandbox shows the most basic usage:
The first thing you need is setting up a module bundler to resolve ECMAScript imports. Above example uses Parcel. You can use other bundlers like Rollup/Webpack, too.
Once you set up a module bundler, you can start importing our component modules, like:
import 'carbon-custom-elements/es/components/dropdown/dropdown';
import 'carbon-custom-elements/es/components/dropdown/dropdown-item';
Once you do that, you can use our components in the same manner as native HTML tags, like:
<bx-dropdown trigger-content="Select an item">
<bx-dropdown-item value="all">Option 1</bx-dropdown-item>
<bx-dropdown-item value="cloudFoundry">Option 2</bx-dropdown-item>
<bx-dropdown-item value="staging">Option 3</bx-dropdown-item>
<bx-dropdown-item value="dea">Option 4</bx-dropdown-item>
<bx-dropdown-item value="router">Option 5</bx-dropdown-item>
</bx-dropdown>
If you just want to try our components for demnstrations, etc., you can use CDNs that support module mapping (e.g. JSPM). With it, you can just import our modules in <script type="module">:
<!DOCTYPE html>
<html>
<head>
<script type="module">
import 'https://jspm.dev/carbon-custom-elements/es/components/dropdown/dropdown.js';
import 'https://jspm.dev/carbon-custom-elements/es/components/dropdown/dropdown-item.js';
</script>
<style type="text/css">
#app {
font-family: 'IBM Plex Sans', 'Helvetica Neue', Arial, sans-serif;
width: 300px;
margin: 2rem;
}
bx-dropdown:not(:defined),
bx-dropdown-item:not(:defined) {
visibility: hidden;
}
</style>
</head>
<body>
<div id="app">
<bx-dropdown trigger-content="Select an item">
<bx-dropdown-item value="all">Option 1</bx-dropdown-item>
<bx-dropdown-item value="cloudFoundry">Option 2</bx-dropdown-item>
<bx-dropdown-item value="staging">Option 3</bx-dropdown-item>
<bx-dropdown-item value="dea">Option 4</bx-dropdown-item>
<bx-dropdown-item value="router">Option 5</bx-dropdown-item>
</bx-dropdown>
</div>
</body>
</html>
Angular users can use our components in the same manner as native HTML tags, too, once you add CUSTOM_ELEMENTS_SCHEMA schema to your Angular module, like:
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
@NgModule({
schemas: [CUSTOM_ELEMENTS_SCHEMA],
declarations: [AppComponent],
imports: [BrowserModule],
bootstrap: [AppComponent],
})
export class AppModule {}
The .d.ts files in carbon-custom-elements package are compiled with TypeScript 3.7. You can use TypeScript 3.7 in your Angular application with upcoming Angular 9.0 release, or with the following instructions, so your application can use those .d.ts files:
true to angularCompilerOptions.disableTypeScriptVersionCheck in tsconfig.jsonpolyfills.ts, change __importDefault TypeScript helper as follows: window.__importDefault = mod => (mod?.__esModule ? mod : { default: mod })
You can use wrapper React components in carbon-custom-elements/es/components-react generated automatically from the custom elements which allows you to use our components seamlessly in your React code. Here's an example:
import React from 'react';
import { render } from 'react-dom';
import BXDropdown from 'carbon-custom-elements/es/components-react/dropdown/dropdown';
import BXDropdownItem from 'carbon-custom-elements/es/components-react/dropdown/dropdown-item';
const App = () => (
<BXDropdown triggerContent="Select an item">
<BXDropdownItem value="all">Option 1</BXDropdownItem>
<BXDropdownItem value="cloudFoundry">Option 2</BXDropdownItem>
<BXDropdownItem value="staging">Option 3</BXDropdownItem>
<BXDropdownItem value="dea">Option 4</BXDropdownItem>
<BXDropdownItem value="router">Option 5</BXDropdownItem>
</BXDropdown>
);
render(<App />, document.getElementById('root'));
Vue users can use our components in the same manner as native HTML tags, without any additional steps!
carbon-custom-elements with old build toolchainyarn installyarn wca && yarn storybookyarn storybook:react (Live demo: https://carbon-custom-elements-react.netlify.com/)yarn storybook:angular (Live demo: https://carbon-custom-elements-angular.netlify.com/)yarn storybook:vue (Live demo: https://carbon-custom-elements-vue.netlify.com/)View available web components at: https://custom-elements.carbondesignsystem.com/. You can see usage information in several ways:
Button kind (kind), where kind is the attribute namebx-modal-closed which typically indicates that an event with such event type is fired. You can also expand the twistie to see the details of the eventTo support IE, you need a couple additional setups:
@babel/preset-env configuration)Here's an example code that shows such setup:
Can be found at here.
> yarn clean
> yarn build
You'll see the build artifacts in /path/to/carbon-custom-elements/es directory.
You can run unit test by:
> gulp test:unit
You can run specific test spec by:
> gulp test:unit -s tests/spec/dropdown_spec.ts
You can choose a browser (instead of Headless Chrome) by:
> gulp test:unit -b Firefox
You can keep the browser after the test (and re-run the test when files change) by:
> gulp test:unit -b Chrome -k
You can prevent code coverate instrumentation code from being generated by:
> gulp test:unit -d
You can update snapshots by:
> gulp test:unit --update-snapshot
Above options can be used together. This is useful to debug your code as you test:
> gulp test:unit -s tests/spec/dropdown_spec.ts -b Chrome -d -k
You can run build integration test by:
> yarn test:integration:build
You can run a specific set of UI test steps (e.g. running tests/integration/build/form-angular_steps.js only) by:
> yarn test:integration:build form-angular_steps
By default Chrome runs in headless mode. You can show Chrome UI by:
> CI=false yarn test:integration:build
You can run UI integration test by:
> yarn test:integration:ui
You can run a specific set of UI test steps (e.g. running tests/integration/ui/dropdown_steps.js only) by:
> yarn test:integration:ui dropdown_steps
By default Chrome runs in headless mode. You can show Chrome UI by:
> CI=false yarn test:integration:ui
FAQs
A Carbon Design System variant that's as easy to use as native HTML elements, with no framework tax, no framework silo.
The npm package carbon-custom-elements receives a total of 141 weekly downloads. As such, carbon-custom-elements popularity was classified as not popular.
We found that carbon-custom-elements demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.