@konemono/nostr-web-components
v0.3.0
Published
[EN/[JA](./README-ja.md)]
Readme
[EN/JA]
Nostr Web Components
A lightweight, easy-to-use Web Components library for integrating Nostr protocol functionality into web applications.
Installation
<script src="https://cdn.jsdelivr.net/npm/@konemono/nostr-web-components@latest/dist/nostr-web-components.iife.js"></script>Usage
Basic Setup with
The component provides a way to share relay configuration to all child components.
Using CDN
<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/@konemono/nostr-web-components@latest/dist/nostr-web-components.iife.js"></script>
</head>
<body>
<nostr-container relays='["wss://relay.damus.io", "wss://nos.lol"]'>
<nostr-note id="note1abc..."></nostr-note>
<nostr-profile user="npub1xyz..."></nostr-profile>
<nostr-list filters='[{"kinds":[1],"limit":10}]'></nostr-list>
</nostr-container>
</body>
</html>Using Individual Components Without
Each component works independently by accessing a shared global client instance internally. Therefore, is optional. For example, to display a single note:
<nostr-note id="note1abc..."></nostr-note>In this case, the note will be fetched using the default relay list internally managed by the global client.
Overriding Relays per Component
You can also specify the relays attribute on individual components to override the container or global relay settings temporarily:
<nostr-note id="note1abc..." relays='["wss://relay.damus.io"]'></nostr-note>
<nostr-profile user="npub1xyz..." relays='["wss://nos.lol"]'></nostr-profile>
<nostr-list filters='[{"kinds":[1],"limit":10}]' relays='["wss://relay.damus.io"]'></nostr-list>Important Notes About
- Multiple instances can exist, but all components share a single global client internally.
- The container mainly serves to propagate relay configuration via context to child components.
- Relay configuration in a container does not create separate or isolated Nostr clients.
- For advanced use cases requiring isolated clients or multiple relay sets, consider managing clients programmatically with the JavaScript API.
Important Notes About
- When multiple
<nostr-stream>components are placed on the same page, the older components may be ignored or cause unexpected behavior. - Currently, only one
<nostr-stream>component per page is supported. - If you need to switch filters dynamically or control behavior, consider managing it with custom logic or replacing the component as needed.
Components
Container component that provides relay configuration to child components via context. This is optional and mainly used to avoid repeating relay configuration on multiple child components.
Attributes:
- relays: JSON array of relay URLs
Displays a Nostr note.
Attributes:
- id: Note ID (note1... or nevent1... format)
- nevent: Alternative to id for nevent format
- relays: Optional relay configuration (overrides container)
- href: Custom URL template (use {id} placeholder)
- target: Link target attribute (default: _blank)
- noLink: Boolean to disable link functionality
- theme: Theme mode - light, dark, or auto (default)
- height: Custom height for the note container
- display: Display mode - card (default) or compact
Examples:
Basic note
<nostr-note id="note1abc..."></nostr-note>Custom URL template
<nostr-note id="note1abc..." href="https://njump.me/{id}"></nostr-note>Dark theme
<nostr-note id="note1abc..." theme="dark"></nostr-note>No link functionality
<nostr-note id="note1abc..." noLink="true"></nostr-note>Different display modes
<nostr-note id="note1abc..." display="card"></nostr-note>
<nostr-note id="note1abc..." display="compact"></nostr-note>Displays a Nostr profile.
Attributes:
- user: Profile identifier (supports hex, npub1..., nprofile1..., and NIP-05 address formats)
- relays: Optional relay configuration (overrides container)
- href: Custom URL template (use {id} placeholder for dynamic URLs)
- target: Link target attribute (default: _blank)
- onclick: JavaScript code to execute on click
- noLink: Boolean to disable link functionality
- display: Display mode - card (default), compact, or name
Examples:
Basic profile card with npub format
<nostr-profile user="npub1xyz..."></nostr-profile>Using hex format
<nostr-profile user="abcdef1234567890..."></nostr-profile>Using nprofile format
<nostr-profile user="nprofile1abc..."></nostr-profile>Using NIP-05 address
<nostr-profile user="[email protected]"></nostr-profile>Custom URL template
<nostr-profile user="npub1xyz..." href="https://primal.net/p/{id}"></nostr-profile>Different display modes
<nostr-profile user="npub1xyz..." display="card"></nostr-profile>
<nostr-profile user="npub1xyz..." display="compact"></nostr-profile>
<nostr-profile user="npub1xyz..." display="name"></nostr-profile>No link functionality
<nostr-profile user="npub1xyz..." noLink="true"></nostr-profile>Custom click handler
<nostr-profile user="npub1xyz..." onclick="console.log('Profile clicked')"></nostr-profile>Displays a list of Nostr events based on filters.
Attributes:
- filters: JSON string of Nostr filters array
- relays: Optional relay configuration (overrides container)
- theme: Theme mode - light, dark, or auto (default)
- limit: Maximum number of events to fetch (default: 50)
Examples:
Basic timeline
<nostr-list filters='[{"kinds":[1],"limit":10}]'></nostr-list>Posts from specific author
<nostr-list filters='[{"kinds":[1],"authors":["npub1xyz..."],"limit":5}]'></nostr-list>Multiple filters
<nostr-list filters='[{"kinds":[1],"limit":10},{"kinds":[6],"limit":5}]'> </nostr-list>Custom relays and theme
<nostr-list
filters='[{"kinds":[1],"limit":20}]'
relays='["wss://relay.damus.io"]'
theme="dark"
limit="30"
>
</nostr-list>Filter Examples
Common filter patterns for :
// Text notes (kind 1)
'[{"kinds":[1],"limit":10}]';
// Posts from specific authors
'[{"kinds":[1],"authors":["npub1...","npub2..."],"limit":5}]';
// Posts with specific hashtags
'[{"kinds":[1],"#t":["nostr","bitcoin"],"limit":10}]';
// Posts from the last hour
'[{"kinds":[1],"since":' + (Math.floor(Date.now() / 1000) - 3600) + ',"limit":20}]';
// Replies to a specific note
('[{"kinds":[1],"#e":["note1abc..."],"limit":10}]');
// Multiple kinds
('[{"kinds":[1,6,7],"limit":15}]');Development
npm install
npm run build
npm run dev # Watch mode
npm run serve # Development serverLicense
MIT