Skip to content

🤝 Contribution

Contributions of any kind are warmly welcomed! Whether you're reporting bugs, requesting features, improving documentation, or submitting code, your input helps make the Expander Card better for everyone.

Feature Requests

Have an idea for a new feature or enhancement? We'd love to hear about it!

To submit a feature request:

  1. Check if a similar request already exists in existing issues
  2. If not, create a new feature request using our template
  3. Describe the feature, its use case, and why it would be valuable

Submit a Feature Request

Template includes:

  • Feature description
  • Use case scenarios
  • Proposed implementation (optional)
  • Alternative solutions considered

Bug Reports

Found something that's not working as expected? Please let us know!

When reporting a bug:

  1. Search existing issues to avoid duplicates
  2. Use our bug report template for consistency
  3. Include reproduction steps, expected vs actual behavior
  4. Add relevant configuration YAML and screenshots if possible
  5. Mention your Home Assistant version and browser

Report a Bug

What to include:

  • Clear description of the issue
  • Steps to reproduce
  • Expected behavior vs actual behavior
  • YAML configuration (sanitized)
  • Screenshots or videos (if applicable)
  • Environment details (HA version, browser, etc.)

Discussions

Want to share ideas, ask questions, or connect with the community? Join our discussions!

Discussion categories:

  • General: Questions and general discussions
  • Ideas: Brainstorm new features and improvements
  • Show and Tell: Share your creative expander card configurations
  • Q&A: Get help from the community

Join the Discussion

Perfect for:

  • Asking "how do I..." questions
  • Sharing your custom configurations
  • Discussing potential features before opening an issue
  • Getting feedback on your setup
  • Helping other users

Pull Requests

The ultimate contribution! We appreciate code contributions, documentation improvements, and bug fixes.

How to Submit a Pull Request

  1. Fork the repository
# Fork via GitHub UI, then clone your fork
git clone https://github.com/YOUR_USERNAME/lovelace-expander-card.git
cd lovelace-expander-card
  1. Create a feature branch
git checkout -b feature/AmazingFeature
# or
git checkout -b fix/BugFix
  1. Make your changes
  2. Write clear, commented code
  3. Follow the existing code style
  4. Test your changes thoroughly

  5. Update documentation if needed

  6. Commit your changes

git add .
git commit -m 'Add some AmazingFeature'

Use clear, descriptive commit messages

  1. Push to your fork
git push origin feature/AmazingFeature
  1. Open a Pull Request
  2. Go to the original repository
  3. Click "New Pull Request"
  4. Select your fork and branch
  5. Provide a clear description of your changes
  6. Link any related issues

Pull Request Guidelines

  • One feature per PR: Keep pull requests focused on a single feature or fix
  • Test thoroughly: Ensure your changes work in different scenarios
  • Update docs: If you add features, update the documentation
  • Code style: Match the existing code formatting and style
  • Commit messages: Use clear, descriptive messages
  • Be patient: Maintainers will review your PR as soon as possible

Local Development Setup

Build & Install

# Install dependencies
npm install
# or
pnpm install

# Start development server
npm run srv

# Build for production
npm run build

# Run es linting
npm run lint

# Fix es linting
npm run lint-fix

Visual Tests

One-time setup — VS Code: open the Terminal › Run Task palette and choose Python: Set up virtual environment.

One-time setup — Command line:

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
playwright install chromium

VS Code — open the Terminal › Run Task palette and choose any pytest: task (run all, run single scenario, update snapshots, etc.).

Command line — activate the virtual environment first, then:

Goal Command
All tests pytest tests/
All tests — update snapshots & doc images SNAPSHOT_UPDATE=1 DOC_IMAGE_UPDATE=1 pytest tests/
Scenario tests only pytest tests/visual/test_scenarios.py
Update scenario snapshots SNAPSHOT_UPDATE=1 pytest tests/visual/test_scenarios.py
Single scenario pytest tests/visual/test_scenarios.py -k expander_collapsed
Single scenario — update snapshot SNAPSHOT_UPDATE=1 pytest tests/visual/test_scenarios.py -k expander_collapsed
Doc images — generate / verify pytest tests/visual/test_doc_images.py
Doc images — update all DOC_IMAGE_UPDATE=1 pytest tests/visual/test_doc_images.py
Doc image audit (no HA needed) pytest tests/test_doc_audit.py

Tip: Start the persistent HA server (python -m ha_testcontainer.ha_server or the HA: Start persistent server VS Code task) before running tests to skip the Docker boot wait on every run.

Tip (debugging): When the persistent server is running, its URL is logged in the terminal. You can open that URL in a browser and log in with the ha-testcontainer default credentials — username testadmin, password testpassword123 — to inspect the HA instance manually. Do not browse to the instance before running tests; doing so may interfere with the test session. If you have already browsed to it, stop the server and start it again before running tests.

Docs

Go to docs folder and install zensical

# cd docs
cd docs

# Install zensical https://zensical.org/docs/get-started/
...

# build docs
zensical build --clean

# start server to see updates in realtime
zensical serve

Open browser on http://localhost:8000

Other Ways to Contribute

  • Documentation: Help improve or translate documentation
  • Examples: Share your expander card configurations in discussions
  • Support: Help answer questions from other users
  • Testing: Test beta releases and provide feedback
  • Spread the word: Star the repo and tell others about it

Code of Conduct

Be respectful, constructive, and welcoming. We're all here to make the Expander Card better together.

Questions?

Not sure where to start? Feel free to:

Thank you for contributing! 🎉