[EN/[JA](./README-ja.md)]
# Nostr Web Components
A lightweight, easy-to-use Web Components library for integrating Nostr protocol functionality into web applications.
## Installation
```html
```
## Usage
### Basic Setup with
The component provides a way to share relay configuration to all child components.
#### Using CDN
```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:
```html
```
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:
```html
```
### 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 `` components are placed on the same page, the older components may be ignored or cause unexpected behavior.
- Currently, only one `` 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
```html
```
Custom URL template
```html
```
Dark theme
```html
```
No link functionality
```html
```
Different display modes
```html
```
###
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
```html
```
Using hex format
```html
```
Using nprofile format
```html
```
Using NIP-05 address
```html
```
Custom URL template
```html
```
Different display modes
```html
```
No link functionality
```html
```
Custom click handler
```html
```
###
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
```html
```
Posts from specific author
```html
```
Multiple filters
```html
```
Custom relays and theme
```html
```
## Filter Examples
Common filter patterns for :
```js
// 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
```bash
npm install
npm run build
npm run dev # Watch mode
npm run serve # Development server
```
## License
MIT